Connect to GitHub

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

• Import new GitHub repositories with a couple clicks during dbt Cloud project setup.
• Clone repos using HTTPS rather than SSH.
• Trigger Continuous integration(CI) builds when pull requests are opened in GitHub.

Prerequisites

• For On-Premises GitHub deployment, reference importing a project by git URL to set up your connection instead. Some git features are limited with this setup.
  • Note — Single tenant accounts offer enhanced connection options for integrating with an On-Premises GitHub deployment setup using the native integration. This integration allows you to use all the features of the integration, such as triggering CI builds. The dbt Labs infrastructure team will coordinate with you to ensure any additional networking configuration requirements are met and completed. To discuss details, contact dbt Labs support or your dbt Cloud account team.
• You must be a GitHub organization owner in order to install the dbt Cloud application in your GitHub organization. To learn about GitHub organization roles, see the GitHub documentation.
• The GitHub organization owner requires Owner or Account Admin permissions when they log into dbt Cloud to integrate with a GitHub environment using organizations.
• You may need to temporarily provide an extra dbt Cloud user account with Owner or Account Admin permissions for your GitHub organization owner until they complete the installation.

Installing dbt Cloud in your GitHub account

You can connect your dbt Cloud account to GitHub by installing the dbt Cloud application in your GitHub organization and providing access to the appropriate repositories. To connect your dbt Cloud account to your GitHub account:

1. From dbt Cloud, 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

4. In the Linked accounts section, set up your GitHub account connection to dbt Cloud 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 Cloud application.

5. Select the GitHub organization and repositories dbt Cloud should access.

   Installing the dbt Cloud application into a GitHub organization

6. Assign the dbt Cloud 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 Cloud 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.

Limiting repository access in GitHub

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

Configuring the dbt Cloud app

Authenticate your personal GitHub account

After the dbt Cloud administrator sets up a connection to your organization's GitHub account, you need to authenticate using your personal account. You must connect your personal GitHub profile to dbt Cloud to use the dbt Cloud IDE and CLI and verify your read and write access to the repository.

GitHub profile connection

• dbt Cloud developers on the Enterprise plan must each connect their GitHub profiles to dbt Cloud. This is because the dbt Cloud IDE verifies every developer's read / write access for the dbt repo.

• dbt Cloud developers on the Team plan don't need to each connect their profiles to GitHub, however, it's still recommended to do so.

To connect a personal GitHub account:

1. From dbt Cloud, 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 Cloud in a grant screen.

Authorizing the dbt Cloud app for developers

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

You can now use the dbt Cloud IDE or dbt Cloud CLI.

FAQs

How can I fix my .gitignore file?

A .gitignore file specifies which files git should intentionally ignore or 'untrack'. dbt Cloud 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 dbt Cloud IDE — this usually indicates a problem with the .gitignore file. The file may be missing or lacks the required entries for dbt Cloud to work correctly.

Fix in the dbt Cloud 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 Cloud 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:

# ✅ 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.

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

6. Once the IDE restarts, go to the File Explorer 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 IDE again using the same procedure as step 5.

9. Once the 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 dbt Cloud 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).

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:

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 dbt Cloud IDE, and open the project that you're fixing.
9. Rollback your repo to remote 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 Cloud.
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:

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 dbt Cloud IDE, and open the project that you're fixing.
11. Rollback your repo to remote 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 Cloud.
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 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 Cloud, you'll need to import your existing repository into your new provider.

   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, GitLab, Azure DevOps)

2. Go back to dbt Cloud and set up your integration for the new git provider, if needed.

3. Disconnect the old repository in dbt Cloud by going to Account Settings and then Projects. Click on the Repository link, then click Edit and Disconnect.

   Disconnect and reconnect your git repository in your dbt Cloud Account Settings pages.

4. 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.

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

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