GitHub repository integration
By setting up the GitHub repository integration, you enable the DX Catalog to read file contents from your repositories. This is required to use file matching rules.
Prerequisites
To connect GitHub to the DX Catalog:
- Your GitHub user account must be an Organization owner or Enterprise owner.
- You must add DX IP addresses to your allowlist 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
- Navigate to the relevant link below to create a new GitHub App.
If you are using GitHub Enterprise Cloud:
-
Navigate to the URL below, replacing
ENTERPRISE_NAMEwith your GitHub enterprise name: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:
-
Navigate to the URL below, replacing
ORGANIZATION_NAMEwith your GitHub organization name:https://github.com/organizations/ORGANIZATION_NAME/settings/apps/new?public=false&url=https://getdx.com&metadata=read&contents=read&webhook_active=false
Step 2
When you open one of the URLs above, the GitHub App settings and permissions are pre-populated. You must still provide a name for the app. To avoid naming conflicts with other GitHub Apps, we recommend naming your app [COMPANYNAME] DX - Repository Integration.
Below are the read-only GitHub App permissions required by DX, which are pre-populated:
| Scope | Permission | Description |
|---|---|---|
| Repository | Metadata | Read-only — required to list repositories |
| Repository | Contents | Read-only — required to read file contents |
Step 3
Scroll to the bottom of the page and click the Create GitHub App button.
Step 4
After you create the app, the GitHub App ID appears at the top of the page. Copy this ID and store it in a secure location so you can enter it into DX later.
Step 5
On the same screen, scroll down to Private keys and click Generate a private key. This will initiate a download of a PEM file. Copy the content of the file and store it in a secure location so you can enter it into DX later.
Step 6
In the sidebar navigation, click Install App. 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. You may return and add more at a later time.
- By default, public repositories are not imported.
Step 7
- Navigate to Catalog Settings in DX and scroll to the Repository integrations section. Click the Add integration button.
- Enter the credentials you have generated in the previous steps.
- The credentials and permission scopes will be verified and the repository integration will be saved.