---
title: "GitHub Repository Files"
canonical_url: "https://docs.getdx.com/connectors/github-repository-files/"
md_url: "https://docs.getdx.com/connectors/github-repository-files.md"
last_updated: "2026-06-18"
---
# GitHub Repository Files
By enabling the GitHub Repository Files connector, you can import a list of files present on the default branch of each repository. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports. This connector does not read the _contents_ of any files; it only lists files and their metadata (relative path, mode, size, and SHA).
Before proceeding, please make sure that you have first enabled the GitHub connector by following the steps [here](https://docs.getdx.com/connectors/github/). 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)
- allowlist [DX IP addresses](https://docs.getdx.com/allowlisting-dx/) if your GitHub instance is behind a firewall or has IP restrictions
## Setup instructions
Follow the steps below to connect GitHub Repository Files 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&contents=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&contents=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 Repository Files** 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 |
#### 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.
{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.
{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. If you would like public repositories to be imported, please contact DX Support.
{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.
## API reference
The table below lists the specific API endpoints that are used by DX.
| Endpoint | Documentation | Permissions Needed |
|------------------------------------------------|---------------|------------------------|
| /orgs/{org}/repos | [Link](https://docs.github.com/en/rest/repos/repos#list-organization-repositories) | metadata:read |
| /repos/{repo}/git/trees/HEAD | [Link](https://docs.github.com/en/rest/git/trees?apiVersion=2022-11-28#get-a-tree) | contents: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 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 Repository Files 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:
```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"
```
> **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.
> **Important**: The JWT token is only valid for `/app/*` endpoints (like `/app/installations`). To access organization or repository endpoints, you must exchange the JWT for an installation access token in Step 3 below.
#### Step 2: Test App Installations
Use the JWT token from Step 1 to verify that your GitHub App can access installations:
The response will include installation objects. Note that `account.login` is your organization name, and `id` is your installation ID—you'll need the installation ID for the next steps.
#### Step 3: Check Installation Permissions
For each installation ID returned in Step 2, check its permissions (replace `YOUR_INSTALLATION_ID` with an actual installation ID):
#### Step 4: Generate an Installation Access Token
Exchange your JWT for an installation access token (replace `YOUR_INSTALLATION_ID` with an installation ID from Step 2):
The response will contain a short-lived installation access token:
```json
{
"token": "ghs_abcdef1234567890...",
"expires_at": "2025-10-28T12:00:00Z",
"permissions": {
"metadata": "read",
"contents": "read"
}
}
```
Use this `token` value as `INSTALLATION_ACCESS_TOKEN` in all following curl examples. This token allows you to access organization and repository endpoints.
#### Step 5: Test Organization Repositories Access
This verifies that your GitHub App can access organization repositories (replace `YOUR_ORG_NAME` with your organization name):
The `YOUR_ORG_NAME` value comes from the `account.login` field returned in Step 3 when you checked installation permissions. This endpoint confirms that your GitHub App installation has permission to view repositories under that organization.
#### Step 6: Test Git Tree Access
This verifies that your GitHub App can access file listings (replace `YOUR_ORG_NAME` and `YOUR_REPO_NAME` with your values):
The response will include the list of all files in a repository.
## 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](https://docs.getdx.com/connectors/github/#credential-fields) (`settings.github_app_id` and `secrets.private_key_pem`).
- [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/)
---
## Sitemap
[Overview of all docs pages](/llms.txt)