> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datafold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Connect Datafold to GitHub to enable automated data diffs on pull requests, CI/CD testing integration, and code-level lineage tracking.

<Note>
  **PREREQUISITES**

  * Datafold Admin role
  * Your GitHub account must be a member of the GitHub organization where the Datafold app is to be installed
  * Approval of your request to add the Datafold app to your repo must be granted by a GitHub repo admin or GitHub organization owner.
</Note>

Go to **Settings** → **Repositories**, click **Add new integration**, and choose **GitHub: CI** or **GitHub: Migration Agent**. Leave **Authentication** set to **GitHub App installation**.

<Frame>
  <img src="https://mintcdn.com/datafold/6RjzI3yTGWikzfSn/images/github_ci_app_installation.png?fit=max&auto=format&n=6RjzI3yTGWikzfSn&q=85&s=32d8f342182cf2f803db407fe109d33e" width="1049" height="721" data-path="images/github_ci_app_installation.png" />
</Frame>

1. Pick your GitHub **Organization** from the dropdown. If it isn't listed, click **Add Datafold GitHub app to new org** to install the app — GitHub will redirect you to log in and select the organization, where you can grant access to all repositories or specific ones. Use **Sync Existing Installations** to refresh the list if you installed the app elsewhere.
2. Select the **Repository** to connect.
3. Click **Save**.

<Tip>
  If you lack permission to add the Datafold app, request approval from a GitHub admin.

  After installing or changing repository access in GitHub, click **Sync Existing Installations** to refresh the repositories shown in the dropdown.
</Tip>

<Note>
  VPC deployments are an Enterprise feature. Please email [sales@datafold.com](mailto:sales@datafold.com) to enable your account.
</Note>

## Connect with a fine-grained Personal Access Token (PAT)

As an alternative to installing the GitHub App, you can connect a repository with a [fine-grained Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). This is useful when you can't (or don't want to) install an org-wide GitHub App — for example, to scope Datafold's access to a single repository.

In the integration form, set **Authentication** to **Personal access token**. The form then shows the required permissions, the token field, and a repository URL field.

<Frame>
  <img src="https://mintcdn.com/datafold/6RjzI3yTGWikzfSn/images/github_ci_pat.png?fit=max&auto=format&n=6RjzI3yTGWikzfSn&q=85&s=929a66424f5b8a0a1cea87c601740538" width="1049" height="721" data-path="images/github_ci_pat.png" />
</Frame>

### Create the token in GitHub

Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens) scoped to the repository you want to connect, and grant these **repository permissions**:

| Permission      | Required access                                                               |
| --------------- | ----------------------------------------------------------------------------- |
| Metadata        | Read                                                                          |
| Contents        | Read *(Read and write for Data Migration Agent, which commits files)*         |
| Pull requests   | Read and write                                                                |
| Commit statuses | Read and write                                                                |
| Webhooks        | Read and write *(optional — lets Datafold install the webhook automatically)* |

<Note>
  Grant **Contents: Read and write** if you'll use the repository for Data Migration Agent (DMA), which needs to commit translated files and open pull requests. Read-only Contents is sufficient for CI/CD data diffs.
</Note>

### Configure the integration in Datafold

1. Paste the token into the **Personal access token** field. Datafold uses it to list the repositories the token can access.
2. *(GitHub Enterprise Server only)* Set **GitHub API URL** to your instance's API endpoint. Leave it blank for github.com — it defaults to `https://api.github.com`.
3. Select or enter the **Repository URL** to connect (click **Refresh** to list repositories the token can access).
4. Click **Save**.

<Tip>
  If you omit the optional **Webhooks** permission, Datafold can't install the webhook for you. After saving, you'll see manual setup instructions with a generated secret — add a webhook in your repository's **Settings → Webhooks** pointing at the displayed URL, using that secret, and select the **Pull requests** and **Pushes** events.
</Tip>

## GitHub integration for VPC / single-tenant Datafold deployments

### Create a GitHub application

VPC clients of Datafold need to create their own GitHub app, rather than use the shared Datafold GitHub application.

Start by navigating to **Settings** → **Global Settings**.

<Frame>
  <img src="https://mintcdn.com/datafold/9DgdnO4sVNte36u-/images/onprem_github_settings-4ba347a4179f693ad9cf851188d3cd3c.png?fit=max&auto=format&n=9DgdnO4sVNte36u-&q=85&s=064ce50091eaab88a16f0314e60103b0" width="2522" height="1252" data-path="images/onprem_github_settings-4ba347a4179f693ad9cf851188d3cd3c.png" />
</Frame>

To begin the set up process, enter the domain that was registered for the VPC deployment in [AWS](/datafold-deployment/dedicated-cloud/aws) or [GCP](/datafold-deployment/dedicated-cloud/gcp). Then, enter the name of the GitHub organization where you'd like to install the application. When filled, click **Create GitHub App**.

This will redirect the admin to GitHub, where they may need to authenticate. **The GitHub user must be an admin of the GitHub organization.**

After authentication, you should be directed to enter a description for the GitHub App. After entering the description, click **Create GitHub app**.

Once the application is created, you should be returned to the Datafold settings screen. The button should then have disappeared, and the details for the GitHub App should be visible.

<Frame>
  <img src="https://mintcdn.com/datafold/9DgdnO4sVNte36u-/images/onprem_github_confirmation-040de7316a509d880b13d6be431da24d.png?fit=max&auto=format&n=9DgdnO4sVNte36u-&q=85&s=1f647e225a50e347520543a74fb723f5" width="1421" height="1017" data-path="images/onprem_github_confirmation-040de7316a509d880b13d6be431da24d.png" />
</Frame>

### Making the GitHub application public

If you have a private GitHub instance with multiple organizations and want to use the Datafold app across all of them, you'll need to make the app public on your private server.

You can do so in GitHub by following these steps:

1. Navigate to the GitHub organization where the app was created.
2. Click **Settings**.
3. Go to **Developer Settings** → **GitHub Apps**.
4. Select the **Datafold app**.
5. Click **Advanced**, then **Make public**.

<Note>
  The app will be public **only on your private GitHub server**, ensuring it can be accessed across all your organizations.
</Note>

### Configure GitHub in Datafold

If you see this screen with all the details, you've successfully created a GitHub App! Now that the app is created, you have to install it using the [GitHub integration setup](/integrations/code-repositories/github).