Automatically post deployment status to GitHub, GitLab, or Bitbucket when deployments start, complete, or fail. Deployment status will appear on commits, pull requests, and merge requests in your Git provider UI.

**Note:** This integration is currently in beta. Contact support to enable beta features for your account.

## How It Works

When a deployment runs, DeployHQ will post the status to your Git provider:

- **GitHub**: Creates deployment and deployment status via GitHub Deployments API with clickable links back to DeployHQ
- **GitLab**: Creates deployment via GitLab Deployments API
- **Bitbucket**: Posts build status via Bitbucket Build Status API (note: Bitbucket uses Build Status instead of Deployments)

The status will appear on:

- Commit pages
- Pull/Merge request pages
- Branch pages (GitHub and GitLab only)

## Setting Up Deployment Notifications

### Prerequisites

1. Your project must have a repository configured
2. Your repository must be hosted on GitHub, GitLab, or Bitbucket
3. Your account must have beta features enabled

### Setup Steps

1. Navigate to your project's **Integrations** page
2. Click **New Integration**
3. Select **Deployment Notifications** from the service picker

{screenshot: 640}

4. **Authorize your Git provider** 

- You must authorize DeployHQ with your Git provider before creating the integration:
- If not already authorized, click **Connect [Provider Name]** to start the OAuth flow
- Grant the requested permissions (see Permissions section below for details)
- You'll be redirected back to the integration page after successful authorization

5. Review the environment mapping for your servers
6. Choose when to trigger the integration:

   - When deployment starts
   - When deployment completes
   - When deployment fails
7. Select which servers or server groups to post status for, or leave **Trigger integration when any server or group deployed** checked to apply to all deployments
8. Click **Create Integration** to finish

**Note:** The Create Integration button will be disabled until you complete OAuth authorization with the required permissions.

## Environment Mapping

The environment name posted to your Git provider is determined by:

1. **Server/Server Group Environment Field** - If set, this value is used
2. **Server/Server Group Name** - Falls back to using the parameterized server name

### Examples

- Server name: "AWS Production", Environment: "production" → Posts as **production**
- Server name: "Staging Server", Environment: (empty) → Posts as **staging-server**
- Server name: "Development Environment", Environment: "dev" → Posts as **dev**

To set the environment field:

1. Navigate to your server or server group settings
2. Find the **Environment** field
3. Enter a value like "production", "staging", or "development"
4. Save your changes

## Permissions

Each Git provider requires specific OAuth permissions to post deployment status. The integration uses a separate OAuth connection per provider.

### GitHub

**Required OAuth scope:** `repo_deployment` or `repo`

DeployHQ will request these scopes during authorization:

- `repo` - Full repository access
- `repo_deployment` - Create deployments and deployment statuses

**What you'll see:**

- A permission box showing the required `repo_deployment` scope
- If missing permissions: A warning with a **Re-authorize with GitHub** button
- The Create Integration button will be disabled until you authorize with the correct scopes

### GitLab

**Required OAuth scope:** `api`

DeployHQ will request this scope during authorization:

- `api` - Full API access including deployments

**What you'll see:**

- A permission box showing the required `api` scope
- If missing permissions: A warning with a **Re-authorize with GitLab** button
- The Create Integration button will be disabled until you authorize with the correct scope

### Bitbucket

**Required OAuth scopes:** `deployments:write` or `repository:write`

DeployHQ will request these scopes during authorization:

- `repository:write` - Write access to repositories
- `deployments:write` - Post build status to commits

**What you'll see:**

- A permission box showing the required `deployments:write` scope
- If missing permissions: A warning with a **Re-authorize with Bitbucket** button
- The Create Integration button will be disabled until you authorize with the correct scopes

**Note:** OAuth authorization is separate from your repository connection. Even if your repository uses SSH keys, you can still use OAuth for deployment status integration.

## Viewing Deployment Status

After setting up the integration, deployment status will automatically appear in your Git provider:

### GitHub

- Navigate to a commit page to see deployment status with clickable links to DeployHQ
- Pull requests will show deployment status checks
- Click the deployment status to view the deployment report in DeployHQ
- Use the "Deployments" section to see deployment history

### GitLab

- Navigate to **Operate** > **Environments** to see deployment status
- Merge requests will show deployment information
- Deployments are created with the commit SHA and environment name

### Bitbucket

- Navigate to a commit page to see build status (Bitbucket displays this as build status, not deployments)
- Pull requests will show build status activity
- Status includes a link back to the DeployHQ deployment report

## Troubleshooting

### Status not appearing

- **Verify OAuth authorization**: Check that you've completed OAuth authorization from the integration page (not the repository settings)
- **Check required permissions**: Ensure the OAuth connection has the correct scopes for your provider
- **Integration enabled**: Verify the integration is enabled and configured correctly
- **Server selection**: Ensure you have selected the correct servers or server groups

### Missing or incorrect permissions

If you see a warning about missing permissions in the integration page:

1. Click the **Re-authorize with [Provider]** button shown in the warning
2. Grant the requested permissions during the OAuth flow
3. You'll be redirected back to the integration page
4. Verify the warning is gone and the Create Integration button is enabled

**Important:** Re-authorization must be done from the integration page, not the repository settings, as each uses different OAuth scopes.

### Create Integration button is disabled

The button will be disabled with the text "Authorize Git Provider First" if:

- You haven't completed OAuth authorization for your Git provider
- Your OAuth authorization is missing the required permissions

Click the **Connect [Provider]** or **Re-authorize** button to fix this.

### Multiple integrations

You can create multiple Deployment Notifications integrations for different server groups or deployment scenarios. Each integration can have different trigger conditions and server selections.

### Legacy connections

If your repository was connected using SSH keys or API tokens (before OAuth), you can still use this integration. The OAuth authorization for deployment status is separate and independent from your repository connection method.