By integrating GitHub with DX, you can analyze pull requests, pull request reviews, repositories, and issues. Please visit our schema explorer 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, GitHub Security, GitHub Copilot, and GitHub Commits. Each GitHub-related connection in DX should utilize a separate GitHub App or API token to avoid rate limit issues.

Prerequisites

To connect GitHub to DX, you need:

a GitHub account that is an Organization owner or Enterprise owner
if your GitHub instance is behind a firewall or has IP restrictions, you need to allowlist DX IP addresses

Setup instructions

Follow the steps below to connect GitHub 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&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

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 full set of required GitHub App permissions:

Repository permissions:
- Read-only access to Deployments
- Read-only access to Issues
- Read-only access to Metadata
- Read-only access to Pull requests
Organization permissions:
- Read-only access to Members

In addition, under Organization permissions, please enable Read-only access to Administration to import organization-level Copilot metrics; for enterprise-level Copilot metrics, please instead enable the GitHub Copilot Usage connector.

Step 2

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

Step 3

The 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 4

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 5

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, please contact DX Support.

Step 6

Navigate to the connector setup form in DX.
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, go to your organization's Developer Settings and click on GitHub Apps.

From there, click on Edit for the GitHub App you are using for DX and then navigate to the Permissions & events tab. After making changes, scroll down to the bottom of the page and click Save changes.

To apply these 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.

API Reference

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

Endpoint	Reference
/orgs/{org}/repos	List Organization Repositories
/orgs/{org}/copilot/usage	GitHub Copilot Usage
/orgs/{org}/team/{team_slug}/copilot/usage	GitHub Copilot Usage
/orgs/{org}/members	Managing Organization Members
/orgs/{org}/teams	Managing Teams
/orgs/{org}/team/{team_id}/members	List Team Members
/orgs/{org}/outside_collaborators	Outside Collaborators
/repos/{repo}/pulls	List Pull Requests
/repos/{repo}/pulls/{number}	Get a Pull Request
/repos/{repo}/pulls/{number}/reviews	List Reviews for a Pull Request
/repos/{repo}/pulls/{number}/comments	List Review Comments on a Pull Request
/repos/{repo}/pulls/{number}/commits	List Commits on a Pull Request
/repos/{repo}/commits	List Commits
/repos/{repo}/issues/{number}/events	List Issue Events
/repos/{repo}/issues	List Issues
/repos/{repo}/labels	List Labels for a Repository

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.
`no_resources`	Your GitHub App installation cannot access any repositories.
`private_key_needed`	The key passed in is not an RSA private key.

Webhooks

DX supports GitHub webhooks ingestion to sync pull request data in real-time. This may be beneficial for large GitHub organizations that have difficulty keeping data up-to-date in DX through batch imports.

To enable webhook ingestion, follow the steps below:

Go to Organization settings -> Webhooks
Click Add webhook button
For the payload URL, enter your instance URL (yourinstance.getdx.net) followed by /webhooks/github
For content type, select application/json
Enter the secret provided to you by your DX account manager
Select Let me select individual events.
1. Uncheck Pushes
2. Check Pull requests and Pull request reviews

Here's an example configuration: