GitHub

By integrating GitHub with DX, you can analyze pull requests, pull request reviews, repositories, and issues. DX populates the tables listed below and does not read or access your source code.

In addition to the GitHub connector, you can setup additional connectors for GitHub Actions, GitHub Security, GitHub Copilot, GitHub Commits, GitHub Projects, and GitHub Pull Request Files. Each GitHub credential in DX should utilize a separate GitHub App ID and API token to avoid rate limit issues.

Tables populated

These are the tables populated by this connector.

The base GitHub connector does not populate tables from separate GitHub connectors such as github_deployment_events, github_pull_files, github_repository_files, and Copilot usage/billing table families. Use the corresponding connector page for those tables.

Use the schema explorer for column-level details in each table.

GitHub conditional schemas

DX supports optional GitHub conditional schemas for additional table families, including GitHub Pull Descriptions, GitHub Repository Properties, GitHub Issues, GitHub Project Pull Request Links (requires the GitHub Projects connector), GitHub Check Runs, and GitHub Releases.

For details on how to manage conditional schemas, see Conditional schemas.

Prerequisites

To connect GitHub to DX, you need:

• a GitHub user account that is an Organization owner or Enterprise owner
• if Copilot metrics are desired, an enabled Copilot metrics API access policy
• 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 to DX.

Data connection

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&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&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 to avoid naming collisions with other GitHub Apps.

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

Copilot metrics permission

To collect org-level Copilot metrics through this connector, add the optional Organization: Copilot metrics permission (Read-only). Whether you should add it depends on your GitHub setup:

Note: If you use GitHub Enterprise, do not enable org-level Copilot metrics here. Org-level metrics can be incomplete for GitHub Enterprise and can duplicate data. Use the enterprise GitHub Copilot Metrics and GitHub Copilot Billing connectors to attribute Copilot cost by team, group, and contributor.

The Repository Checks permission is optional and only required if DX should list check runs for commits via the GitHub Checks API.

Repository Contents permission

Add the optional Repository Contents permission (Read-only) if you use either of the following:

• GitHub Releases: Required to enable the GitHub Releases conditional schema. Each active GitHub credential must have Contents: Read-only before the schema can be enabled.
• AI Code Insights on private repositories: When GitHub rewrites a pull request’s commits, such as through a merge queue or Update branch with rebase, DX downloads the diffs of the commits before and after the rewrite to match them, and credits each new commit with the AI attribution of the commit it replaced. DX stores only which commits match, not the diffs. Without this permission, rewritten commits in private repositories use only their own attribution. Public repositories don’t need it.

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, this connector imports only private repositories. If you are using the data extractor for GitHub, extractor discovery includes all repository visibilities (public, private, and internal) unless you set GITHUB_EXTRACT_ONLY_PRIVATE_REPOS=true.

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.

Updating permissions

To update your GitHub App permissions:

1. Go to your organization’s Developer Settings and click on GitHub Apps.
2. Click *Edit** for the GitHub App you are using for DX.
3. Navigate to the Permissions & events tab to make changes.
4. After making changes, scroll down to the bottom of the page and click Save changes.
5. To apply the changes, go to the Install App tab, click on the gear icon for each organization listed, and then click and accept the Review request as shown in the images below.

Copilot metrics API

Your GitHub Copilot metrics API access policy for an organization can be managed from the following URL (replace ORGANIZATION_NAME with your organization’s name):

https://github.com/organizations/ORGANIZATION_NAME/settings/copilot/policies

To enable Copilot metrics collection:

1. Navigate to the Policies tab in your organization’s Copilot settings.
2. Scroll to the Copilot metrics API access section.
3. Select Enabled from the dropdown menu to allow API access to Copilot usage metrics.
4. Click Save to apply your changes.

When enabled, this allows DX to retrieve aggregated Copilot usage data for your organization, including metrics such as acceptance rates, active users, and language breakdowns.

Webhooks

DX optionally supports GitHub webhooks to sync pull request data in real-time, which is recommended in order to ensure real-time data accuracy in DX. See GitHub webhooks for setup instructions.

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 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, generate a JWT token using your GitHub App credentials:

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"

Step 2: Test Endpoints

Replace YOUR_JWT_TOKEN with the token generated above before running these commands.

1. Test App Installations

This verifies 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'

2. Check Installation Permissions

For each installation ID returned above, check its permissions:

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:

• members
• metadata
• pull_requests

If you receive a 401 Unauthorized error, your JWT token may be invalid or expired. If you receive a 403 Forbidden error or empty results, your GitHub App may not have the required permissions or installations.

Data Cloud API

Once the initial connection is created successfully, GitHub credentials can be managed via the Data Cloud API.

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

Credential fields

{
  "id": 456,
  "settings": {
    "github_app_id": "123456"
  },
  "secrets": {
    "private_key_pem": "-----BEGIN RSA PRIVATE KEY-----\nMIIEfakePrivateKeyContentHere\n-----END RSA PRIVATE KEY-----"
  }
}