GitHub Deployments

By enabling the GitHub Deployments connector, you can import production deployment events from GitHub and track Deploy frequency. In combination with other GitHub connectors, this enables reports about the relationship between deployments and opened or merged pull requests. See the API documentation below and the schema explorer for the data DX imports. DX does not read or access your source code.

Use this connector when your teams already create GitHub deployment events for production releases. For custom workflows, monorepos, or deployment systems outside GitHub, use deployments.create instead.

GitHub Deployments creates catalog services using the repository name where the deployment occurred. If your organization has repositories with the same name across organizations, business units, or product areas, review your catalog after the first import to confirm services were created as expected.

Before proceeding, enable the GitHub connector. Each GitHub credential in DX should use a separate GitHub App ID and API token to avoid rate limit issues.

Prerequisites

To connect GitHub Deployments to DX, you need:

• a GitHub user account that is an Organization owner or Enterprise owner
• an existing GitHub connector set up in DX
• allowlist DX IP addresses if your GitHub instance is behind a firewall or has IP restrictions

Setup instructions

Follow the steps below to connect GitHub Deployments to DX.

Step 1

• If you are using GitHub Enterprise Cloud, browse to the URL below with ENTERPRISE_NAME replaced:

  https://github.com/enterprises/ENTERPRISE_NAME/settings/apps/new?public=false&url=https://getdx.com&metadata=read&actions=read&deployments=read&issues=read&pull_requests=read&members=read&request_oauth_on_install=false&setup_on_update=false&webhook_active=false

• If you are using GitHub Enterprise Server or GitHub Team Edition, browse to the URL below with ORGANIZATION_NAME replaced:

  https://github.com/organizations/ORGANIZATION_NAME/settings/apps/new?public=false&url=https://getdx.com&metadata=read&deployments=read&issues=read&pull_requests=read&members=read&organization_administration=read&request_oauth_on_install=false&setup_on_update=false&webhook_active=false

Step 2

This will pre-populate settings and permissions, but you’ll need to manually enter a name for your GitHub App. We recommend naming your app [COMPANYNAME] DX - GitHub Deployments to avoid naming collisions with other GitHub Apps.

Below are the read-only GitHub App permissions required by DX:

Step 3

Scroll to the bottom of the page and click the “Create GitHub App” button.

Step 4

The GitHub App ID will be shown at the top of the subsequent screen. Copy this ID down so it can be entered into DX later.

Step 5

On the same screen, scroll down to the “Private keys” heading and click “Generate a private key” which will initiate a download of a PEM file. Copy the contents of this file to be entered into DX later.

Step 6

Click on the “Install App” link in the sidebar navigation and then click “Install” beside your GitHub organization.

• To get your initial data imported as quickly as possible, please select only your most important repositories initially, then come back and select more later.
• By default, public repositories are not imported. If you would like public repositories to be imported, you can configure this after setting up the connector in your settings.

Step 7

• Navigate to the connections page in DX and select + Connection in the top right.
• Enter the credentials you have generated in the previous steps. Refer to the information below for errors and troubleshooting.
• Configure how DX will import deployments from GitHub:
  • Optionally, choose whether or not to import deployments from archived, public, and forked repositories.
• After the first successful import, additional settings become available on the connection’s edit page:
  • Production Environments: Select which environments should be treated as production from a dropdown populated with environments discovered during import. If no environments are selected, deployments that GitHub itself marks as production are used, based on the production_environment boolean from the GitHub API.
  • Ignored Repositories: Select repositories to exclude from deployment imports.

API reference

The table below lists the specific API endpoints that are used by DX.

Errors

The table below lists potential error codes when adding a connection in DX.

Curl commands

When connection verification fails

When DX verifies a GitHub Deployments connection, it checks app installations to ensure proper access with the required permissions. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

Step 1: Generate JWT Token

First, create a bash script to generate a JWT token for authentication. Replace YOUR_GITHUB_APP_ID with your GitHub App ID and PRIVATE_KEY_FILE with your actual private key content:

APP_ID="YOUR_GITHUB_APP_ID"
PRIVATE_KEY_FILE="PRIVATE_KEY_FILE"

b64url() { base64 | tr -d '\n=' | tr '+/' '-_'; }

HEADER=$(printf '{"alg":"RS256","typ":"JWT"}' | b64url)
NOW=$(date +%s); EXP=$((NOW + 300))
PAYLOAD=$(printf '{"iat":%s,"exp":%s,"iss":"%s"}' "$NOW" "$EXP" "$APP_ID" | b64url)

tmp=$(mktemp)
tr -d '\r' < "$PRIVATE_KEY_FILE" > "$tmp"
SIG=$(printf '%s' "$HEADER.$PAYLOAD" | openssl dgst -sha256 -sign "$tmp" -binary | b64url)
rm -f "$tmp"

echo "$HEADER.$PAYLOAD.$SIG"

Note: The PRIVATE_KEY_FILE should contain your complete private key including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.

Run this script to generate your JWT token, then use that token in the curl commands below.

Step 2: Test App Installations

Use the JWT token from Step 1 to verify that your GitHub App can access installations:

curl -H 'Authorization: Bearer YOUR_JWT_TOKEN' -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/app/installations'

Step 3: Check Installation Permissions

For each installation ID returned above, check its permissions (replace YOUR_INSTALLATION_ID with an actual installation ID):

curl -H 'Authorization: Bearer YOUR_JWT_TOKEN' -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/app/installations/YOUR_INSTALLATION_ID'

The response should include a list of installations with permissions. For successful verification, the installations should have at least these permissions:

• actions
• deployments
• issues
• members
• metadata
• pull_requests

Data Cloud API

Once the initial connection is created successfully, credentials can be managed via the Data Cloud API. This connector uses the same credential fields as GitHub (settings.github_app_id and secrets.private_key_pem).

• credentials.create
• credentials.update
• credentials.info
• credentials.list
• credentials.delete