# Connect to GitHub

dbt platform

Connecting your GitHub account to dbt provides convenience and another layer of security to dbt:

* Import new GitHub repositories with a couple clicks during dbt project setup.
* Clone repos using HTTPS rather than SSH.
* Trigger [Continuous integration](../../deploy/continuous-integration.md)(CI) builds when pull requests are opened in GitHub.

GitHub Enterprise Cloud (`ghe.com`) domains

If your organization uses GitHub Enterprise Cloud, hosted on a `ghe.com` domain, the shared dbt GitHub App can't reach it. Note that `ghe.com` accounts are cloud-managed (not on-premises), but this limitation still applies.

Enterprise and Enterprise+ accounts can connect by registering a [custom GitHub application](#custom-github-application) instead. On other plans, use [importing a project by git URL](./import-a-project-by-git-url.md) with SSH/deploy keys. Your organization's SSH URL configuration may require additional steps, and some native integration features are unavailable with the git URL method.

For additional help with your specific setup, contact [dbt Support](mailto:support@getdbt.com) or your dbt account team.

## Prerequisites

* **GitHub permissions**: You must be a GitHub organization owner to [install the application](./connect-github.md#installing-dbt-in-your-github-account). Learn more about [GitHub organization](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization) roles.
* **dbt permissions**: Your GitHub organization owner also needs [*Owner*](../manage-access/self-service-permissions.md) or [*Account Admin*](../manage-access/enterprise-permissions.md) permissions in dbt platform. If needed, create a temporary account with these [permissions](../manage-access/enterprise-permissions.md) for the installation.
* **On-premises GitHub or EU-hosted GitHub**: On Enterprise and Enterprise+ plans, you can use the native integration by registering a [custom GitHub application](#custom-github-application). On other plans, [connect using a Git URL](./import-a-project-by-git-url.md), which supports [fewer](./import-a-project-by-git-url.md#limited-integration) Git features.

Case-sensitive repository names

When specifying a GitHub repository in the dbt platform using the UI, API, or Terraform provider, the repository name must exactly match the case used in the GitHub URL to avoid cloning errors or job failures. For example, if the URL of your repository is `github.com/my-org/MyRepo`, enter the name as `MyRepo`, not `myrepo`.

## Choose your GitHub application

dbt connects to GitHub through a GitHub App. You have two options:

* [Shared dbt application (default)](#installing-dbt-in-your-github-account), available to any org connecting to `github.com`.
* Your own [custom GitHub application](#custom-github-application), available in private beta to Enterprise and Enterprise+ accounts on MT or ST using GitHub Enterprise Server or GitHub with EU data residency. Reach out to your account manager to join the beta. [Private beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles")

You can use one GitHub application per dbt account, not one per project.

## Installing dbt in your GitHub account

You can connect your dbt account to GitHub by installing the dbt application in your GitHub organization and providing access to the right repos:

1. From dbt, click on your account name in the left side menu and select **Account settings**.
2. Select **Personal profile** under the **Your profile** section.
3. Scroll down to **Linked accounts**.

[![Navigated to Linked Accounts under your profile](/img/docs/dbt-platform/platform-configuring-dbt-platform/connecting-github/github-connect-1.png?v=2 "Navigated to Linked Accounts under your profile")](#)Navigated to Linked Accounts under your profile

4. In the **Linked accounts** section, set up your GitHub account connection to dbt by clicking **Link** to the right of GitHub. This redirects you to your account on GitHub where you will be asked to install and configure the dbt application.

5. Select the GitHub organization and repos dbt should access.

   [![Installing the dbt application into a GitHub organization](/img/docs/dbt-platform/platform-configuring-dbt-platform/connecting-github/github-app-install.png?v=2 "Installing the dbt application into a GitHub organization")](#)Installing the dbt application into a GitHub organization

6. Assign the dbt GitHub App the following permissions:

   * Read access to metadata
   * Read and write access to Checks
   * Read and write access to Commit statuses
   * Read and write access to Contents (Code)
   * Read and write access to Pull requests
   * Read and write access to Webhooks
   * Read and write access to Workflows

7. Once you grant access to the app, you will be redirected back to dbt and shown a linked account success state. You are now personally authenticated.

8. Ask your team members to individually authenticate by connecting their [personal GitHub profiles](#authenticate-your-personal-github-account).

## Limiting repository access in GitHub

If you are your GitHub organization owner, you can also configure the dbt GitHub application to have access to only select repositories. This configuration must be done in GitHub, but we provide an easy link in dbt to start this process.

[![Configuring the dbt app](/img/docs/dbt-platform/platform-configuring-dbt-platform/connecting-github/configure-github.png?v=2 "Configuring the dbt app")](#)Configuring the dbt app

## Custom GitHub application [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing")[Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing")[Private beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles")

Available in private beta

Configuring a custom GitHub app is available in private beta. To join, reach out to your account manager.

The shared dbt GitHub App is hosted per [region](../about-platform/access-regions-ip-addresses.md), so it can only reach repositories on `github.com`. If your organization runs [GitHub Enterprise Server](https://docs.github.com/en/enterprise-server@3.14/admin/overview/about-github-enterprise-server) or [GitHub with EU data residency](https://github.com/enterprise/data-residency), register your own GitHub application and point dbt at it.

An account admin (or security admin) can set this up once:

1. [Register a GitHub application](#register-a-github-application) in your GitHub organization
2. [Add your GitHub application to dbt](#add-your-github-application-to-dbt)

Then each developer on the account needs to [relink their GitHub profile](#relink-your-github-profile).

### Register a GitHub application

Repo availability

dbt platform doesn’t support concurrent integrations with public and private GitHub repositories. To register a GitHub App, you need a private repository. Disconnect your configured public repository before you follow the steps in this section.

We recommend creating the app in your GitHub organization instead of a personal account to ensure the connection doesn't break should a person leave. For the full walkthrough on the GitHub side, check out GitHub's guide to [registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).

1. In dbt, go to **Account settings** > **Integrations** > **Git** and expand the **GitHub** section. Select **Copy** next to **Redirect URL** — you need it in the next step.

2. In your GitHub organization, go to **Settings** > **Developer settings** > **GitHub Apps** and select **New GitHub App**.

3. Enter the following:

   | Field               | Value                                                                                                                                                           |
   | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **GitHub App name** | Something recognizable, such as `dbt platform`                                                                                                                  |
   | **Homepage URL**    | Your dbt [access URL](../about-platform/access-regions-ip-addresses.md)                                                      |
   | **Redirect URL**    | The **Redirect URL** you copied from dbt                                                                                                                        |
   | **Webhook**         | Leave **Active** selected and enter any placeholder URL (such as <https://example.com>) in the **Webhook URL** field. dbt doesn't use it but GitHub requires it |

4. Grant the app these repository permissions:

   * Read access to metadata
   * Read and write access to Checks
   * Read and write access to Commit statuses
   * Read and write access to Contents (Code)
   * Read and write access to Pull requests
   * Read and write access to Webhooks
   * Read and write access to Workflows

5. Select **Create GitHub App**. GitHub generates an **App ID** and a **Client ID**.

6. Generate a **Client secret** and copy it somewhere safe as GitHub only shows it once.

7. Under **Private keys**, select **Generate a private key**. GitHub downloads a `.pem` file. You'll then paste its contents into dbt.

8. Install the app into your organization and note its **install URL**. Refer to GitHub's docs on [sharing your app via an install link](https://docs.github.com/en/apps/sharing-github-apps/sharing-your-github-app#sharing-your-github-app-via-an-install-link).

If you're a Business Critical customer using [IP restrictions](../secure/ip-restrictions.md), make sure your GitHub instance's CIDRs are allowed, or the connection will fail.

### Add your GitHub application to dbt

Existing GitHub connections break

If your account already uses the shared dbt GitHub App, switching to your own application invalidates every existing GitHub profile link. Everyone on the account has to [relink their GitHub profile](#relink-your-github-profile) before they can develop or run CI. Plan the switch with your team.

1. In dbt, go back to **Account settings** > **Integrations** > **Git** and expand the **GitHub** section.

2. Enter the following:

   | Field               | Value                                                                                                                                                           |
   | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **GitHub base URL** | Your GitHub hostname. Use `https://github.com` for GitHub.com, or your own hostname for GitHub Enterprise Server, such as `https://github.yourgreatcompany.com` |
   | **App ID**          | The **App ID** from your GitHub app                                                                                                                             |
   | **Client ID**       | The **Client ID** from your GitHub app                                                                                                                          |
   | **Client secret**   | The client secret you generated                                                                                                                                 |
   | **Private key**     | The full contents of the `.pem` file you downloaded, including the `BEGIN` and `END` lines                                                                      |
   | **Install URL**     | Optional. Your app's install link                                                                                                                               |

   [![Adding your own GitHub application under Account settings, Integrations, Git](/img/docs/dbt-platform/platform-configuring-dbt-platform/connecting-github/github-application-platform.png?v=2 "Adding your own GitHub application under Account settings, Integrations, Git")](#)Adding your own GitHub application under Account settings, Integrations, Git

3. Select **Save**. dbt validates the credentials against GitHub. If something isn't right, dbt shows an error and doesn't save the configuration.

dbt now routes all GitHub authorization for this account through your application.

### Relink your GitHub profile

Every developer authenticates against the account's GitHub application, so repo access matches what your GitHub admin actually granted them. After an admin adds or changes the application, relink your profile:

1. From dbt, click your account name in the left side menu and select **Account settings**.
2. Select **Personal profile** under the **Your profile** section.
3. Scroll to **Linked accounts** and select **Unlink** next to GitHub if an old connection is still listed.
4. Select **Link** and authorize your organization's GitHub application.

For the full walkthrough, refer to [Authenticate your personal GitHub account](#authenticate-your-personal-github-account).

### Remove a GitHub integration

Account admins and security admins can delete a GitHub integration from **Account settings** > **Integrations** > **Git**.

Removing an integration disconnects everyone

Deleting the integration breaks repo access and CI for the *whole* account until you configure a new one. You can't stage a replacement first, because an account supports only one GitHub integration at a time.

### Limitations

Note that the following limitations apply:

* One GitHub application per dbt account. You can't set a different application per project.
* You can't configure multiple GitHub integrations on the same account.
* Only account admins and security admins can create, update, or delete a GitHub integration.

## Authenticate your personal GitHub account

After the dbt administrator [sets up a connection](./connect-github.md#installing-dbt-in-your-github-account) to your organization's GitHub account, you need to authenticate using your personal account. You must connect your personal GitHub profile to dbt to use the [Studio IDE](../studio-ide/develop-in-studio.md) and [CLI](../dbt-cli-installation.md) and verify your read and write access to the repository.

GitHub profile connection

* dbt developers on the [Enterprise or Enterprise+ plan](https://www.getdbt.com/pricing/) must each connect their GitHub profiles to dbt. This is because the Studio IDE verifies every developer's read / write access for the dbt repo.

* dbt developers on the [Starter plan](https://www.getdbt.com/pricing/) don't need to each connect their profiles to GitHub, however, it's still recommended to do so.

If your account uses a [custom GitHub application](#custom-github-application), you authorize that application instead of the shared dbt app, and your repository access mirrors your GitHub App installation.

To connect a personal GitHub account:

1. From dbt, click on your account name in the left side menu and select **Account settings**.

2. Select **Personal profile** under the **Your profile** section.

3. Scroll down to **Linked accounts**. If your GitHub account is not connected, you’ll see "No connected account".

4. Select **Link** to begin the setup process. You’ll be redirected to GitHub, and asked to authorize dbt in a grant screen.

[![Authorizing the dbt app for developers](/img/docs/dbt-platform/platform-configuring-dbt-platform/connecting-github/github-auth.png?v=2 "Authorizing the dbt app for developers")](#)Authorizing the dbt app for developers

5. Once you approve authorization, you will be redirected to dbt, and you should now see your connected account.

You can now use the Studio IDE or dbt CLI.

## FAQs

How can I fix my .gitignore file?

A `.gitignore` file specifies which files git should intentionally ignore or 'untrack'. dbt indicates untracked files in the project file explorer pane by putting the file or folder name in *italics*.

If you encounter issues like problems reverting changes, checking out or creating a new branch, or not being prompted to open a pull request after a commit in the Studio IDE — this usually indicates a problem with the [.gitignore](https://github.com/dbt-labs/dbt-starter-project/blob/main/.gitignore) file. The file may be missing or lacks the required entries for dbt to work correctly.

The following sections describe how to fix the `.gitignore` file in:

 Fix in the Studio IDE

To resolve issues with your `gitignore` file, adding the correct entries won't automatically remove (or 'untrack') files or folders that have already been tracked by git. The updated `gitignore` will only prevent new files or folders from being tracked. So you'll need to first fix the `gitignore` file, then perform some additional git operations to untrack any incorrect files or folders.

1. Launch the Studio IDE into the project that is being fixed, by selecting **Develop** on the menu bar.
2. In your **File Explorer**, check to see if a `.gitignore` file exists at the root of your dbt project folder. If it doesn't exist, create a new file.
3. Open the new or existing `gitignore` file, and add the following:

```bash
# ✅ Correct 
target/
dbt_packages/
logs/
# legacy -- renamed to dbt_packages in dbt v1
dbt_modules/
```

* **Note** — You can place these lines anywhere in the file, as long as they're on separate lines. The lines shown are wildcards that will include all nested files and folders. Avoid adding a trailing `'*'` to the lines, such as `target/*`.

For more info on `gitignore` syntax, refer to the [Git docs](https://git-scm.com/docs/gitignore).

4. Save the changes but *don't commit*.
5. Restart the IDE by clicking on the three dots next to the **IDE Status button** on the lower right corner of the IDE screen and select **Restart IDE**.

[![Restart the IDE by clicking the three dots on the lower right or click on the Status bar](/img/docs/dbt-platform/platform-ide/restart-ide.png?v=2 "Restart the IDE by clicking the three dots on the lower right or click on the Status bar")](#)Restart the IDE by clicking the three dots on the lower right or click on the Status bar

6. Once the Studio IDE restarts, go to the **File Catalog** to delete the following files or folders (if they exist). No data will be lost:

   * `target`, `dbt_modules`, `dbt_packages`, `logs`

7. **Save** and then **Commit and sync** the changes.

8. Restart the Studio IDE again using the same procedure as step 5.

9. Once the Studio IDE restarts, use the **Create a pull request** (PR) button under the **Version Control** menu to start the process of integrating the changes.

10. When the git provider's website opens to a page with the new PR, follow the necessary steps to complete and merge the PR into the main branch of that repository.

    * **Note** — The 'main' branch might also be called 'master', 'dev', 'qa', 'prod', or something else depending on the organizational naming conventions. The goal is to merge these changes into the root branch that all other development branches are created from.

11. Return to the Studio IDE and use the **Change Branch** button, to switch to the main branch of the project.

12. Once the branch has changed, click the **Pull from remote** button to pull in all the changes.

13. Verify the changes by making sure the files/folders in the `.gitignore` file are in italics.

[![A dbt project on the main branch that has properly configured gitignore folders (highlighted in italics).](/img/docs/dbt-platform/platform-ide/gitignore-italics.png?v=2 "A dbt project on the main branch that has properly configured gitignore folders (highlighted in italics).")](#)A dbt project on the main branch that has properly configured gitignore folders (highlighted in italics).

 Fix in the Git provider

Sometimes it's necessary to use the git providers web interface to fix a broken `.gitignore` file. Although the specific steps may vary across providers, the general process remains the same.

There are two options for this approach: editing the main branch directly if allowed, or creating a pull request to implement the changes if required:

### Edit in main branch

When permissions allow it, it's possible to edit the `.gitignore` directly on the main branch of your repo. Here are the following steps:

1. Go to your repository's web interface.
2. Switch to the main branch and the root directory of your dbt project.
3. Find the `.gitignore` file. Create a blank one if it doesn't exist.
4. Edit the file in the web interface, adding the following entries:

```bash
target/
dbt_packages/
logs/
# legacy -- renamed to dbt_packages in dbt v1
dbt_modules/
```

5. Commit (save) the file.
6. Delete the following folders from the dbt project root, if they exist. No data or code will be lost:
   * `target`, `dbt_modules`, `dbt_packages`, `logs`
7. Commit (save) the deletions to the main branch.
8. Switch to the Studio IDE , and open the project that you're fixing.
9. [Rollback your repo to remote](./version-control-basics.md#the-git-button-in-the-cloud-ide) in the IDE by clicking on the three dots next to the **IDE Status** button on the lower right corner of the IDE screen, then select **Rollback to remote**.
   * **Note** — Rollback to remote resets your repo back to an earlier clone from your remote. Any saved but uncommitted changes will be lost, so make sure you copy any modified code that you want to keep in a temporary location outside of dbt.
10. Once you rollback to remote, open the `.gitignore` file in the branch you're working in. If the new changes aren't included, you'll need to merge the latest commits from the main branch into your working branch.
11. Go to the **File Explorer** to verify the `.gitignore` file contains the correct entries and make sure the untracked files/folders in the .gitignore file are in *italics*.
12. Great job 🎉! You've configured the `.gitignore` correctly and can continue with your development!

### Unable to edit main branch

If you can't edit the `.gitignore` directly on the main branch of your repo, follow these steps:

1. Go to your repository's web interface.
2. Switch to an existing development branch, or create a new branch just for these changes (This is often faster and cleaner).
3. Find the `.gitignore` file. Create a blank one if it doesn't exist.
4. Edit the file in the web interface, adding the following entries:

```bash
target/
dbt_packages/
logs/
# legacy -- renamed to dbt_packages in dbt v1
dbt_modules/
```

5. Commit (save) the file.
6. Delete the following folders from the dbt project root, if they exist. No data or code will be lost:
   * `target`, `dbt_modules`, `dbt_packages`, `logs`
7. Commit (save) the deleted folders.
8. Open a merge request using the git provider web interface. The merge request should attempt to merge the changes into the 'main' branch that all development branches are created from.
9. Follow the necessary procedures to get the branch approved and merged into the 'main' branch. You can delete the branch after the merge is complete.
10. Once the merge is complete, go back to the Studio IDE, and open the project that you're fixing.
11. [Rollback your repo to remote](./version-control-basics.md#the-git-button-in-the-cloud-ide) in the Studio IDE by clicking on the three dots next to the **Studio IDE Status** button on the lower right corner of the Studio IDE screen, then select **Rollback to remote**.
    * **Note** — Rollback to remote resets your repo back to an earlier clone from your remote. Any saved but uncommitted changes will be lost, so make sure you copy any modified code that you want to keep in a temporary location outside of dbt.
12. Once you rollback to remote, open the `.gitignore` file in the branch you're working in. If the new changes aren't included, you'll need to merge the latest commits from the main branch into your working branch.
13. Go to the **File Explorer** to verify the `.gitignore` file contains the correct entries and make sure the untracked files/folders in the .gitignore file are in *italics*.
14. Great job 🎉! You've configured the `.gitignore` correctly and can continue with your development!

For more info, refer to this [detailed video](https://www.loom.com/share/9b3b8e2b617f41a8bad76ec7e42dd014) for additional guidance.

How to migrate git providers

To migrate from one git provider to another, refer to the following steps to avoid minimal disruption:

1. Outside of dbt, you'll need to import your existing repository into your new provider. By default, connecting your repository in one account won't automatically disconnected it from another account.

   As an example, if you're migrating from GitHub to Azure DevOps, you'll need to import your existing repository (GitHub) into your new Git provider (Azure DevOps). For detailed steps on how to do this, refer to your Git provider's documentation (Such as [GitHub](https://docs.github.com/en/migrations/importing-source-code/using-github-importer/importing-a-repository-with-github-importer), [GitLab](https://docs.gitlab.com/ee/user/project/import/repo_by_url.html), [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/import-git-repository?view=azure-devops))

2. Go back to dbt and set up your [integration for the new Git provider](./configure-git.md), if needed.

3. Disconnect the old repository in dbt by going to **Account Settings** and then **Projects**.

4. Click on the **Repository** link, then click **Edit** and **Disconnect**.

   [![Disconnect and reconnect your Git repository in your dbt Account settings page.](/img/docs/dbt-platform/disconnect-repo.png?v=2 "Disconnect and reconnect your Git repository in your dbt Account settings page.")](#)Disconnect and reconnect your Git repository in your dbt Account settings page.

5. Click **Confirm Disconnect**.

6. On the same page, connect to the new Git provider repository by clicking **Configure Repository**

   * If you're using the native integration, you may need to OAuth to it.

7. That's it, you should now be connected to the new Git provider! 🎉

Note — As a tip, we recommend you refresh your page and Studio IDE before performing any actions.

Why does dbt reject my custom GitHub application details?

dbt validates your GitHub application against GitHub before saving it, so an invalid configuration is rejected instead of quietly breaking your team's connection. If you see an error when you save, check these in order:

* **App ID**: Use the **App ID** from your GitHub app's settings page, not the client ID or the installation ID.
* **Private key**: Paste the entire contents of the `.pem` file, including the `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----` lines. If you lost the file, generate a new private key in GitHub.
* **Client ID**: Paste the **Client ID** from your GitHub app.
* **GitHub base URL**: Use the hostname of your GitHub instance with no trailing slash and no `/api/v3` path, for example `https://github.yourgreatcompany.com`.
* **Client secret**: GitHub only shows this once. If you didn't copy it, generate a new one.
* **Network access**: Your GitHub instance must be reachable from dbt. If you use [IP restrictions](../secure/ip-restrictions.md), confirm the relevant CIDRs are allowed.

For setup steps, refer to [Custom GitHub application](./connect-github.md#custom-github-application), available in private beta.
