--- title: "GitHub" canonical_url: "https://docs.getdx.com/connectors/github/" md_url: "https://docs.getdx.com/connectors/github.md" last_updated: "2026-06-18" --- # GitHub By integrating GitHub with DX, you can analyze pull requests, pull request reviews, repositories, and issues. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports—note that DX does not read or access your source code. In addition to the GitHub connector, you can setup additional connectors for [GitHub Actions](https://docs.getdx.com/connectors/github-actions/), [GitHub Security](https://docs.getdx.com/connectors/github-security/), [GitHub Copilot](https://docs.getdx.com/connectors/github-copilot-metrics/), [GitHub Commits](https://docs.getdx.com/connectors/github-commits), [GitHub Projects](https://docs.getdx.com/connectors/github-projects/), and [GitHub Pull Request Files](https://docs.getdx.com/connectors/github-pull-request-files/). Each GitHub credential in DX should utilize a separate GitHub App ID and API token to avoid rate limit issues. ## Prerequisites To connect GitHub to DX, you need: - a GitHub user account that is an [Organization owner](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-owners) or [Enterprise owner](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners) - if Copilot metrics are desired, an enabled [Copilot metrics API access policy](https://docs.github.com/en/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api#prerequisites) - allowlist [DX IP addresses](https://docs.getdx.com/allowlisting-dx/) if your GitHub instance is behind a firewall or has IP restrictions ## Setup instructions > This connector supports multiple credentials. You can add additional credentials to distribute API requests across multiple tokens, improving import speed and reliability. To learn more, go to [Can I use multiple API credentials for a data connector?](https://docs.getdx.com/knowledgebase/can-i-use-multiple-api-credentials-for-a-data-connector/) 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&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** to avoid naming collisions with other GitHub Apps. Below are the read-only GitHub App permissions required by DX: | Scope | Permission | Description | | ------------ | --------------- | ------------------------------------------------------- | | Repository | Deployments | Read-only | | Repository | Issues | Read-only | | Repository | Metadata | Read-only | | Repository | Pull requests | Read-only | | Repository | Checks | Read-only _(optional — required for commit check runs)_ | | Organization | Members | Read-only | | Organization | Copilot metrics | Read-only _(optional — required for Copilot metrics)_ | | Organization | Administration | Read-only _(optional — required for Premium requests)_ | The **Organization Copilot metrics** permission is optional and only required if you want to collect organization-level Copilot metrics through this connector. This is intended for non-enterprise customers, or enterprise customers who want org-level Copilot data. For enterprise-level Copilot metrics, use the dedicated [GitHub Copilot Metrics (Enterprise)](https://docs.getdx.com/connectors/github-copilot-metrics/) connector instead. The **Repository Checks** permission is optional and only required if DX should list [check runs for commits](https://docs.github.com/en/rest/checks/runs?apiVersion=2026-03-10#list-check-runs-for-a-git-reference) via the GitHub Checks API. ![](https://docs.getdx.com/assets/images/connectors/github/github-repo-permissions.png){class="max-w-xl mx-auto"} #### 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. ![](https://docs.getdx.com/assets/images/connectors/github/github-app.png){class="max-w-xl mx-auto"} #### 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. ![](https://docs.getdx.com/assets/images/connectors/github/private-key.png){class="max-w-xl mx-auto"} #### 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. ![](https://docs.getdx.com/assets/images/connectors/github/repository-access.png){class="max-w-xl mx-auto"} #### 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. ![](https://docs.getdx.com/assets/images/connectors/github/update-permissions.png){class="max-w-xl mx-auto"} ![](https://docs.getdx.com/assets/images/connectors/github/permission-update-request.png){class="max-w-xl mx-auto"} #### 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. ![](https://docs.getdx.com/assets/images/connectors/github/copilot-api-access.png){class="max-w-2xl mx-auto"} ### Webhooks DX supports GitHub webhooks ingestion to sync pull request data in real-time. This is recommended in order to ensure real-time data accuracy in DX. GitHub webhooks can be configured at the repository, organization, and GitHub App levels. For detailed instructions on creating webhooks, refer to the [official GitHub documentation](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks). The steps below describe adding webhooks at the organization level: 1. Go to **Organization settings > Webhooks** 2. Click **Add webhook** 3. For the Payload URL input field, enter **https://yourinstance.getdx.net/webhooks/github** but with your unique subdomain 4. Enter your DX webhooks secret which can be found on the Connections admin page 5. Select "Let me select individual events" - Uncheck **Pushes** - Check **Pull requests** and **Pull request reviews** - (Optional) Check **Pull request review comments** to update the review comment count in real-time Here's what your settings should look like: ![](https://docs.getdx.com/assets/images/connectors/github/webhooks.png){class="max-w-xl mx-auto"} ## API reference The table below lists the specific API endpoints that are used by DX. | Endpoint | Documentation | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | /orgs/{org}/repos | [Link](https://docs.github.com/en/rest/repos/repos#list-organization-repositories) | | /orgs/{org}/members | [Link](https://docs.github.com/en/rest/orgs/members#list-organization-members) | | /orgs/{org}/teams | [Link](https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#list-teams) | | /orgs/{org}/team/{team_id}/members | [Link](https://docs.github.com/en/rest/teams/members#list-team-members) | | /orgs/{org}/outside_collaborators | [Link](https://docs.github.com/en/rest/orgs/outside-collaborators) | | /repos/{owner}/{repo}/pulls | [Link](https://docs.github.com/en/rest/pulls/pulls#list-pull-requests) | | /repos/{owner}/{repo}/issues | [Link](https://docs.github.com/en/rest/issues/issues#list-issues) | | /repos/{owner}/{repo}/pulls/comments | [Link](https://docs.github.com/en/rest/pulls/comments#list-review-comments-on-pull-requests) | | /repos/{owner}/{repo}/pulls/{pull_number}/reviews | [Link](https://docs.github.com/en/rest/pulls/reviews#list-reviews-for-a-pull-request) | | /repos/{owner}/{repo}/commits/{ref}/check-runs | [Link](https://docs.github.com/en/rest/checks/runs?apiVersion=2026-03-10#list-check-runs-for-a-git-reference) | | /repos/{owner}/{repo}/commits/{ref}/statuses | [Link](https://docs.github.com/en/rest/commits/statuses?apiVersion=2026-03-10#list-commit-statuses-for-a-reference) | | /repos/{repo}/issues/{number}/events | [Link](https://docs.github.com/en/rest/issues/events?apiVersion=2022-11-28#list-issue-events) | | /repos/{repo}/labels | [Link](https://docs.github.com/en/rest/issues/labels#list-labels-for-a-repository) | | /orgs/{org}/copilot/metrics/reports/users-1-day | [Link](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-organization-usage-metrics-for-a-specific-day) | | /organizations/{org}/settings/billing/premium_request/usage | [Link](https://docs.github.com/en/rest/billing/usage?apiVersion=2022-11-28#get-billing-premium-request-usage-report-for-an-organization) | ## Errors The table below lists potential error codes when adding a connection in DX. | Error | Description | |----------------------|------------------------------------------------------------------------------------------------------------------| | `invalid_credentials` | Your API credentials entered are not valid. | | `invalid_permissions` | Your GitHub App installation does not have the permissions required by DX, or is not installed to any GitHub organizations. | | `no_resources` | Your GitHub App installation cannot access any repositories. | | `private_key_needed` | The key passed in is not an RSA private key. | ## 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: ```bash 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](https://docs.getdx.com/datacloudapi/methods/credentials.create/) - [credentials.update](https://docs.getdx.com/datacloudapi/methods/credentials.update/) - [credentials.info](https://docs.getdx.com/datacloudapi/methods/credentials.info/) - [credentials.list](https://docs.getdx.com/datacloudapi/methods/credentials.list/) - [credentials.delete](https://docs.getdx.com/datacloudapi/methods/credentials.delete/) ### Credential fields | Field | Type | Description | | ----- | ---- | ----------- | | `settings.github_app_id` | `String` | The GitHub App ID. | | `secrets.private_key_pem` | `String` | The PEM-encoded private key for the GitHub App. Send as a JSON string with `\n` for newlines. | ```json { "id": 456, "settings": { "github_app_id": "123456" }, "secrets": { "private_key_pem": "-----BEGIN RSA PRIVATE KEY-----\nMIIEfakePrivateKeyContentHere\n-----END RSA PRIVATE KEY-----" } } ``` --- ## Sitemap [Overview of all docs pages](/llms.txt)