---
title: "GitHub repository integration"
canonical_url: "https://docs.getdx.com/catalog/github-repository-integration/"
md_url: "https://docs.getdx.com/catalog/github-repository-integration.md"
last_updated: "2026-06-18"
---

# 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](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).
- You must add DX IP addresses to your [allowlist](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 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_NAME` with 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_NAME` with 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](https://app.getdx.com/catalog/manage/general) 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.
---

## Sitemap

[Overview of all docs pages](/llms.txt)