Connect to GitLab

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

• Import new GitLab repos with a couple clicks during dbt Cloud project setup.
• Clone repos using HTTPS rather than SSH.
• Carry GitLab user permissions through to dbt Cloud or dbt Cloud CLI's git actions.
• Trigger Continuous integration builds when merge requests are opened in GitLab.
  • GitLab automatically registers a webhook in your GitLab repository to enable seamless integration with dbt Cloud.

The steps to integrate GitLab in dbt Cloud depend on your plan. If you are on:

• the Developer or Team plan, read these instructions.
• the Enterprise plan, jump ahead to these instructions.

For dbt Cloud Developer and Team tiers

To connect your GitLab 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.
4. Click Link to the right of your GitLab account.

The Personal profile settings with the Linked Accounts section of the user profile

When you click Link, you will be redirected to GitLab and prompted to sign into your account. GitLab will then ask for your explicit authorization:

GitLab Authorization Screen

Once you've accepted, you should be redirected back to dbt Cloud, and you'll see that your account has been linked to your profile.

For the dbt Cloud Enterprise tier

dbt Cloud enterprise customers have the added benefit of bringing their own GitLab OAuth application to dbt Cloud. This tier benefits from extra security, as dbt Cloud will:

• Enforce user authorization with OAuth.
• Carry GitLab's user repository permissions (read / write access) through to dbt Cloud or dbt Cloud CLI's git actions.

In order to connect GitLab in dbt Cloud, a GitLab account admin must:

1. Set up a GitLab OAuth application.
2. Add the GitLab app to dbt Cloud.

Once the admin completes those steps, dbt Cloud developers need to:

1. Personally authenticate with GitLab from dbt Cloud.

Setting up a GitLab OAuth application

We recommend that before you set up a project in dbt Cloud, a GitLab account admin set up an OAuth application in GitLab for use in dbt Cloud.

For more detail, GitLab has a guide for creating a Group Application.

In GitLab, navigate to your group settings and select Applications. Here you'll see a form to create a new application.

GitLab application navigation

In GitLab, when creating your Group Application, input the following:

Field	Value
Name	dbt Cloud
Redirect URI	https://YOUR_ACCESS_URL/complete/gitlab
Confidential	✅
Scopes	✅ api

Replace YOUR_ACCESS_URL with the appropriate Access URL for your region and plan.

The application form in GitLab should look as follows when completed:

GitLab group owned application form

Click Save application in GitLab, and GitLab will then generate an Application ID and Secret. These values will be available even if you close the app screen, so this is not the only chance you have to save them.

If you're a Business Critical customer using IP restrictions, ensure you've added the appropriate Gitlab CIDRs to your IP restriction rules, or else the Gitlab connection will fail.

Adding the GitLab OAuth application to dbt Cloud

After you've created your GitLab application, you need to provide dbt Cloud information about the app. In dbt Cloud, account admins should navigate to Account Settings, click on the Integrations tab, and expand the GitLab section.

Navigating to the GitLab Integration in dbt Cloud

In dbt Cloud, input the following values:

Field	Value
GitLab Instance	https://gitlab.com
Application ID	copy value from GitLab app
Secret	copy value from GitLab app

Note, if you have a special hosted version of GitLab, modify the GitLab Instance to use the hostname provided for your organization instead - for example https://gitlab.yourgreatcompany.com/.

Once the form is complete in dbt Cloud, click Save.

You will then be redirected to GitLab and prompted to sign into your account. GitLab will ask for your explicit authorization:

GitLab Authorization Screen

Once you've accepted, you should be redirected back to dbt Cloud, and your integration is ready for developers on your team to personally authenticate with.

Personally authenticating with GitLab

dbt Cloud developers on the Enterprise plan must each connect their GitLab profiles to dbt Cloud, as every developer's read / write access for the dbt repo is checked in the dbt Cloud IDE or dbt Cloud CLI.

To connect a personal GitLab 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 GitLab account is not connected, you’ll see "No connected account". Select Link to begin the setup process. You’ll be redirected to GitLab, and asked to authorize dbt Cloud in a grant screen.

Authorizing the dbt Cloud app for developers

Once you approve authorization, you will be redirected to dbt Cloud, and you should see your connected account. You're now ready to start developing in the dbt Cloud IDE or dbt Cloud CLI.

Troubleshooting

Unable to trigger a CI job with GitLab

When you connect dbt Cloud to a GitLab repository, GitLab automatically registers a webhook in the background, viewable under the repository settings. This webhook is also used to trigger CI jobs when you push to the repository.

If you're unable to trigger a CI job, this usually indicates that the webhook registration is missing or incorrect.

To resolve this issue, navigate to the repository settings in GitLab and view the webhook registrations by navigating to GitLab --> Settings --> Webhooks.

Some things to check:

• The webhook registration is enabled in GitLab.
• The webhook registration is configured with the correct URL and secret.

If you're still experiencing this issue, reach out to the Support team at support@getdbt.com and we'll be happy to help!

Errors importing a repository on dbt Cloud project set up

If you don't see your repository listed, double-check that:

• Your repository is in a Gitlab group you have access to. dbt Cloud will not read repos associated with a user.

If you do see your repository listed, but are unable to import the repository successfully, double-check that:

• You are a maintainer of that repository. Only users with maintainer permissions can set up repository connections.

If you imported a repository using the dbt Cloud native integration with GitLab, you should be able to see if the clone strategy is using a deploy_token. If it's relying on an SSH key, this means the repository was not set up using the native GitLab integration, but rather using the generic git clone option. The repository must be reconnected in order to get the benefits described above.

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.

I'm seeing a Gitlab authentication out of date error loop

If you're seeing a 'GitLab Authentication is out of date' 500 server error page - this usually occurs when the deploy key in the repository settings in both dbt Cloud and GitLab do not match.

No worries - this is a current issue the dbt Labs team is working on and we have a few workarounds for you to try:

First workaround

1. Disconnect repo from project in dbt Cloud.
2. Go to Gitlab and click on Settings > Repository.
3. Under Repository Settings, remove/revoke active dbt Cloud deploy tokens and deploy keys.
4. Attempt to reconnect your repository via dbt Cloud.
5. You would then need to check Gitlab to make sure that the new deploy key is added.
6. Once confirmed that it's added, refresh dbt Cloud and try developing once again.

Second workaround

1. Keep repo in project as is -- don't disconnect.
2. Copy the deploy key generated in dbt Cloud.
3. Go to Gitlab and click on Settings > Repository.
4. Under Repository Settings, manually add to your Gitlab project deploy key repo (with Grant write permissions box checked).
5. Go back to dbt Cloud, refresh your page and try developing again.

If you've tried the workarounds above and are still experiencing this behavior - reach out to the Support team at support@getdbt.com and we'll be happy to help!

Can self-hosted GitLab instances only be connected via dbt Cloud Enterprise plans?

Presently yes, this is only available to Enterprise users. This is because of the way you have to set up the GitLab app redirect URL for auth, which can only be customized if you're a user on an Enterprise plan.

Check out our pricing page for more information or feel free to contact us to build your Enterprise pricing.

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.