Deployment Notifications

Last updated on 7th October 2025

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

Deployment Notification

  1. 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
  1. Review the environment mapping for your servers
  2. Choose when to trigger the integration:
  • When deployment starts
  • When deployment completes
  • When deployment fails
    1. 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
    2. 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.