GitHub Projects
By enabling the GitHub Project connector, you can import GitHub projects and issue data. Please refer to the API documentation below and our schema explorer to see what data DX imports.
Before proceeding, please make sure that you have first enabled the GitHub connector by following the steps here. 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 user account that is an Organization owner or Enterprise owner
- 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.
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&issues=read&contents=read&organization_projects=read&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&issues=read&contents=read&organization_projects=read&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 Security to avoid naming collisions with other GitHub Apps.
Below are the read-only GitHub App permissions required by DX:
| Scope | Permission Type | Description |
|---|---|---|
| Repository | Read-only | Access to Metadata |
| Repository | Read-only | Access to Contents |
| Repository | Read-only | Access to Issues |
| Organization | Read-only | Access to Project |
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, please contact DX Support.
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.
API reference
The table below lists the specific API endpoints that are used by DX.
| Endpoint | Documentation | Permissions Needed |
|---|---|---|
| /orgs/{org}/repos | Link | metadata:read |
| /graphql | Link | project:read |
| /repos/{repo}/issues/ | Link | project:read |
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 organization projects. |
private_key_needed |
The key passed in is not an RSA private key. |
Curl commands
When connection verification fails
When DX verifies a GitHub Projects 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. Test Organization Projects Access
For each installation, test access to organization projects:
curl -H 'Authorization: Bearer YOUR_JWT_TOKEN' -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/orgs/YOUR_ORG/projects'The response should include organization projects with the required permissions (repository_projects:read). 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.