What you will be able to do
- Choose between a native git integration and a git clone import for a given provider, plan and hosting model
- Set up the dbt GitHub App, and know when a custom GitHub application is needed and what switching to one breaks
- Configure GitLab on Starter/Developer and Enterprise plans and troubleshoot its webhook and access token
- Set up Azure DevOps with a service principal and know which admins and personal links it requires
Key concept
Native git integration — A provider-specific connection to GitHub, GitLab or Azure DevOps. It is configured once for the dbt account, and then each developer links it on their personal profile. It lets dbt clone over HTTPS, pass provider permissions through and trigger CI from pull or merge requests. A plain git clone import does none of that automatically.
1.Native integration or git clone
A dbt project can reach its repository in two ways, and the choice decides how much dbt can do with it. A native integration exists for three providers: GitHub, GitLab and Azure DevOps. With a native integration you can import repos in a couple of clicks during project setup and clone over HTTPS rather than SSH. dbt also triggers CI builds when a pull request (in GitLab, a merge request) is opened. Every other provider, including Bitbucket and AWS CodeCommit, goes through a git clone import over SSH with a deploy key. The mechanics of that are covered in [connecting a repo by git URL](lesson:2.1).
The git clone route costs you automatic CI. Without a native integration, dbt is never told that a pull request opened, so nothing starts a CI job on its own. You can still run CI, but your own pipeline has to call the dbt Administrative API to start the job.
| Git provider | Native dbt integration | Automated CI job | Plans for native integration |
|---|---|---|---|
| GitHub | Yes | Yes | All dbt plans |
| GitLab | Yes | Yes | All dbt plans |
| Azure DevOps | Yes | Yes | Enterprise, Enterprise+ (Starter and Developer can connect with a deploy key, without automated CI) |
| BitBucket, AWS CodeCommit and others | No | No | Git clone only |
Where the repository is hosted matters as much as the provider. Azure DevOps Server, the on-premise product, is not covered by the native Azure DevOps integration, so it has to be imported by git URL. GitHub Enterprise Cloud on a ghe.com domain is cloud-managed, but the shared dbt GitHub App still cannot reach it. Enterprise and Enterprise+ accounts can register a custom GitHub application instead. Other plans fall back to git URL import, which supports fewer git features.
Checkpoint 1 of 9· Check yourself
A team on the dbt Starter plan hosts its repo on Bitbucket and wants a CI run whenever a pull request opens. What is available to them?
Bitbucket has no native integration on any plan, so dbt cannot start CI jobs automatically. A git clone import plus an API call from the team's own pipeline can still start one.
“leverage the dbt Administrative API to trigger a CI job to run.”Source: docs.getdbt.com
Checkpoint 2 of 9· Exam question
A dbt Cloud customer wants to enable the native GitHub integration for their organization. Who must complete the initial GitHub App installation step, and what GitHub role does that person need to hold?
Correct answer: A — The dbt Cloud Owner or Account Admin, who also holds GitHub Organization Owner rights, installs the dbt GitHub App at the organization level.
- A. Installing the dbt GitHub App is an organization-wide action in GitHub, so it requires someone who is both a dbt Owner/Account Admin and a GitHub Organization Owner to grant the app access to the chosen repositories.
- B. A Developer license alone does not grant the dbt Owner or Account Admin permission needed to start the GitHub App installation flow, and personal GitHub credentials cannot install an organization-level app.
- C. Repository-level Write access in GitHub is not sufficient to install an app at the organization level; the installer needs GitHub Organization Owner permissions to authorize org-wide app access.
- D. Without dbt Owner or Account Admin permissions, this user cannot reach the account-level settings screen where the GitHub App installation is initiated, regardless of their GitHub credentials.
2.GitHub: the shared app and a custom app
dbt connects to GitHub through a GitHub App installed into your GitHub organization. The installer needs two roles at once. They must be a GitHub organization owner, and they must also hold Owner or Account Admin permissions in dbt. If the GitHub org owner has neither dbt role, you can create a temporary dbt account with those permissions for the install.
The install starts from a personal profile: Account settings > Personal profile > Linked accounts, then Link next to GitHub. dbt redirects you to GitHub. There you choose the organization and the repositories dbt may access, then grant the app its permissions: read access to metadata, plus read and write access to checks, commit statuses, contents, pull requests, webhooks and workflows. When GitHub sends you back to dbt, only you are authenticated. Each other developer has to link their own GitHub profile the same way.
Repository names in dbt are case-sensitive. The name must match the case in the GitHub URL exactly, whether you enter it in the UI, the API or the Terraform provider. Write MyRepo, not myrepo, or cloning and jobs fail.
Checkpoint 3 of 9· Check yourself
A dbt Account Admin who is a member of the GitHub organization, but not an owner, tries to install the dbt GitHub App. What blocks them?
The install needs both roles: GitHub organization owner, and Owner or Account Admin in dbt. The dbt role alone does not let you install into a GitHub org.
“You must be a GitHub organization owner to install the application.”Source: docs.getdbt.com
The shared app is hosted per region and can only reach repositories on github.com. Organizations on GitHub Enterprise Server or GitHub with EU data residency register their own GitHub application instead. This is a private beta open to Enterprise and Enterprise+ accounts. An account admin or security admin creates the app once, in the GitHub organization rather than a personal account, so the connection survives if that person leaves. First, copy the Redirect URL from Account settings > Integrations > Git in dbt and paste it into the new app in GitHub. GitHub then provides an App ID, a Client ID, a client secret (shown only once) and a private key .pem file. Back in dbt, enter those along with the GitHub base URL and select Save. dbt checks the credentials against GitHub and will not save a bad configuration.
Two consequences mean the switch needs planning. First, moving an account from the shared app to its own app invalidates every existing GitHub profile link. Nobody can develop or run CI until they relink. Second, an account can have only one GitHub integration. Deleting it breaks repo access and CI for the whole account, and you cannot set up the replacement in advance.
Checkpoint 4 of 9· Match them up
Match each GitHub situation to what dbt requires
Tap a term, then the definition that fits it.
The shared app only reaches github.com, so self-hosted and EU-resident GitHub need a custom app. Switching to a custom app invalidates profile links, and only account or security admins manage the integration.
“The shared dbt GitHub App is hosted per region, so it can only reach repositories on github.com.”Source: docs.getdbt.com
Checkpoint 5 of 9· Exam question
A company on the dbt Cloud Developer plan wants to connect dbt Cloud to a self-managed GitLab instance where every repository belongs to a GitLab group. Which approach matches what the Developer plan actually supports?
Correct answer: A — Configure a single shared GitLab deploy token for the account, since Developer and Starter plans support one deploy token for group-owned repositories.
- A. On Developer and Starter plans, GitLab connects through a single shared deploy token rather than a per-user OAuth application, and that token works against group-owned repositories.
- B. Bring-your-own GitLab OAuth applications are an Enterprise-tier capability; Developer plan accounts cannot register a custom OAuth app for enhanced per-user security.
- C. Per-user GitLab permission enforcement through individually linked accounts is an Enterprise-plan behavior, not something the Developer plan's shared-token model provides.
- D. GitLab does have a native dbt Cloud integration; falling back to generic git clone URL import is unnecessary and skips the deploy-token path the Developer plan already supports.
Sources1
3.GitLab: deploy token or your own OAuth application
GitLab's native integration works on every dbt plan as long as your GitLab subscription is Premium or Ultimate. The dbt plan decides which identity dbt acts as. On Starter and Developer, dbt uses a single GitLab deploy token created by the first user who connects the repository. That shared identity brings three limits:
- every repository users reach from dbt must belong to a GitLab group - all commits and pushes from the Studio IDE appear to come from the same deploy token - GitLab push rules may reject pushes made through dbt, especially when several people commit through that token
Enterprise and Enterprise+ accounts avoid the shared identity by bringing their own GitLab OAuth application. dbt then requires each user to authorize with OAuth, and applies that user's GitLab read/write permissions in the Studio IDE and the dbt platform CLI. A GitLab admin creates the application from the group's Applications settings. Name it dbt, mark it confidential, give it the api scope, and build its Redirect URI from your dbt access URL. In dbt, Account settings > Integrations > GitLab asks for the GitLab Instance, the Application ID and the Secret. The instance is https://gitlab.com, or your own hostname if you self-host. After the admin saves and authorizes the app, each developer links GitLab on their personal profile, because dbt checks every developer's access separately.
Checkpoint 6 of 9· Put it in order
Put the GitLab Enterprise setup in order
- 1.The admin adds the Application ID and Secret under Account settings > Integrations in dbt
- 2.Each developer links their GitLab account from Personal profile > Linked accounts
- 3.A GitLab admin creates a group-owned OAuth application with the api scope
The admin's two steps come first. Developers can only authenticate personally once the application is configured.
“Once the admin completes those steps, dbt developers need to:”Source: docs.getdbt.com
When you connect a repository through the native integration, GitLab creates two things in the background. A webhook, visible in the repository settings, starts CI jobs in dbt when you push. A project access token, named dbt token for GitLab project: <project_id>, reports job run status back to GitLab. dbt refreshes this token automatically, so you never rotate it by hand. If refresh errors persist, disconnect and reconnect the repository to get a fresh token.
Most GitLab failures come from one of these pieces:
- A CI job never starts. The webhook is usually missing or wrong, so check under Settings > Webhooks that it is enabled and has the correct URL and secret.
- A repo is missing from the import list. It usually sits under a user namespace rather than a group, and dbt does not read repos that belong to a user.
- A repo is listed but will not import. You are not a maintainer of the repository.
- The repository's clone strategy uses an SSH key instead of a deploy_token. It was connected with the generic git clone option, not the native integration, and must be reconnected to get the webhook and CI.
Checkpoint 7 of 9· Check yourself
A developer can see their GitLab repo in dbt's import list, but the import fails. What is the most likely cause?
A repo in a personal namespace would not appear in the list at all, and dbt refreshes the access token itself. A repo that is listed but will not import means the user lacks maintainer permissions.
“Only users with maintainer permissions can set up repository connections.”Source: docs.getdbt.com
Sources4
4.Azure DevOps: service principal and personal links
The native Azure DevOps integration covers Azure DevOps cloud accounts on Enterprise and Enterprise+ plans. It offers the same benefits as the other two integrations: click-to-import, HTTPS cloning and CI triggered by pull requests. It also uses OAuth 2.0 to authorize users and applies each user's repository read/write permissions in the Studio IDE and dbt CLI. Azure DevOps Server is not covered and must be imported by git URL.
Deployment runs and CI happen with no one signed in, so dbt needs an identity that is not a person. The recommended method is a service principal. This is a Microsoft Entra ID application that authenticates with a client ID and secret, and dbt uses it for actions such as deployment runs and CI. The older service user is a real Azure user with an Entra ID and a license. It remains available as a legacy option, and you can migrate from it to a service principal. Whichever you choose, you need admins for dbt, Entra ID and Azure DevOps. You also need an Azure admin if Entra ID and Azure DevOps are not connected.
Setting up the service principal takes three stages: register an Entra ID app, connect Azure DevOps to it, then add it to dbt. Two registration details cause most failures:
- Supported account types must be Multitenant, because Microsoft treats Azure DevOps and Entra ID as separate tenants.
- The Redirect URI comes from Account settings > Integrations in dbt, under Azure DevOps. Use the first value, which ends in /complete/azure_active_directory, not the one ending in service_user.
Use a separate Entra ID app from the one you use for SSO. If your tenant does not allow users to consent for themselves, an Entra ID admin must grant tenant-wide admin consent.
Checkpoint 8 of 9· Check yourself
An Entra ID admin registers the dbt app as Single Tenant because the company has only one tenant. What happens?
Microsoft treats Azure DevOps and Entra ID as separate tenants, so the app must be registered as Multitenant.
“for the Entra ID application to work properly, you must select Multitenant.”Source: docs.getdbt.com
The service principal does not replace personal authentication. Anyone who uses the Studio IDE or dbt CLI on the team's Azure DevOps repo links their dbt profile to Azure DevOps through OAuth. They do this from Personal profile > Linked accounts and accept the Azure DevOps App's permission request. Sometimes pull requests stop triggering CI and neither side shows an error. Check two things first: that the repository's Azure DevOps service hooks still exist and point at your dbt account, and that the service principal or service user still has access to the repository. If both look fine, disconnect and reconnect the repository.
Checkpoint 9 of 9· Exam question
A dbt Cloud Enterprise team installed the dbt GitHub App at the organization level, but developers report that commits made through the Studio IDE do not reflect their own GitHub identity. Which two additional steps are required to fix this? (Select two.)(Select 2)
Correct answers: A, B — Each developer links their personal GitHub account under Account Settings → Personal profile → Linked accounts.; Each developer authorizes the dbt GitHub App grant screen when redirected during the personal profile linking flow.
- A. The organization-level app install only grants dbt access to repositories; each individual developer still has to link their own GitHub account so their commits carry their own identity.
- B. Linking the account is completed by authorizing the GitHub grant screen during that flow, which is the step that actually establishes the per-user OAuth connection behind commit attribution.
- C. Reinstalling the app with Owner-level access to personal repositories is not how per-developer identity is established, and granting Owner access to individual repos is not part of this workflow at all.
- D. GitHub App authentication for dbt Cloud relies on the OAuth linking flow rather than manually pasted personal access tokens, so this step plays no role in resolving commit attribution.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.GitHub Enterprise Cloud on ghe.com is cloud-hosted, so the shared dbt GitHub App can reach it.Why is that wrong?
The shared app cannot reach ghe.com accounts. Enterprise and Enterprise+ accounts register a custom GitHub app, and other plans import by git URL.
Covered in Native integration or git clone
2.Developers won't notice a move from the shared GitHub App to a custom app.Why is that wrong?
The switch invalidates every existing GitHub profile link. Everyone must relink before they can develop or run CI.
Covered in GitHub: the shared app and a custom app
3.A GitLab repo under a personal user namespace will show up in dbt's import list.Why is that wrong?
dbt only reads repos in GitLab groups you have access to. Repos that belong to a user are not listed.
Covered in GitLab: deploy token or your own OAuth application
4.The native Azure DevOps integration covers on-premise Azure DevOps Server.Why is that wrong?
It covers Azure DevOps cloud only. Azure DevOps Server is connected by importing the project by git URL.
Covered in Azure DevOps: service principal and personal links
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Clone repos using HTTPS rather than SSH.”
↩︎ Native integration or git clone“Enterprise and Enterprise+ accounts can connect by registering a custom GitHub application instead.”
↩︎ Native integration or git clone“Your GitHub organization owner also needs Owner or Account Admin permissions in dbt platform.”
↩︎ GitHub: the shared app and a custom app“Ask your team members to individually authenticate by connecting their personal GitHub profiles.”
↩︎ GitHub: the shared app and a custom app“the repository name must exactly match the case used in the GitHub URL to avoid cloning errors or job failures.”
↩︎ GitHub: the shared app and a custom app“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.”
↩︎ GitHub: the shared app and a custom app“You can't stage a replacement first, because an account supports only one GitHub integration at a time.”
↩︎ GitHub: the shared app and a custom app“Use the App ID from your GitHub app's settings page, not the client ID or the installation ID.”
↩︎ GitHub: the shared app and a custom app“If your organization uses GitHub Enterprise Cloud, hosted on a ghe.com domain, the shared dbt GitHub App can't reach it.”
↩︎ Exam trap 1“switching to your own application invalidates every existing GitHub profile link.”
↩︎ Exam trap 2“You must be a GitHub organization owner to install the application.”
↩︎ Checkpoint“You can use one GitHub application per dbt account, not one per project.”
↩︎ Prediction“The shared dbt GitHub App is hosted per region, so it can only reach repositories on github.com.”
↩︎ Checkpoint - 2.
“leverage the dbt Administrative API to trigger a CI job to run.”
↩︎ Native integration or git clone“If your git provider has a native dbt integration, you can seamlessly set up continuous integration (CI) jobs directly within dbt.”
↩︎ Key concept - 3.
“Instead, you can import a project by git URL to connect to an Azure DevOps Server.”
↩︎ Native integration or git clone“Connecting an Azure DevOps cloud account is available for organizations using the dbt Enterprise or Enterprise+ plans.”
↩︎ Azure DevOps: service principal and personal links“you will need admins for dbt, Azure Entra ID, and Azure DevOps to complete the integration.”
↩︎ Azure DevOps: service principal and personal links“Confirm the Azure DevOps service hooks for the repository still exist and point to your dbt account.”
↩︎ Azure DevOps: service principal and personal links“dbt's native Azure DevOps integration does not support Azure DevOps Server (on-premise).”
↩︎ Exam trap 4 - 4.
“You must have a GitLab Premium or Ultimate account.”
↩︎ GitLab: deploy token or your own OAuth application“dbt Starter and Developer plans use a single GitLab deploy token created by the first user who connects the repository”
↩︎ GitLab: deploy token or your own OAuth application“dbt Enterprise and Enterprise+ customers have the added benefit of bringing their own GitLab OAuth application to dbt.”
↩︎ GitLab: deploy token or your own OAuth application“If you're unable to trigger a CI job, this usually indicates that the webhook registration is missing or incorrect.”
↩︎ GitLab: deploy token or your own OAuth application“dbt automatically refreshes this project access token for you, which means you never have to manually rotate it.”
↩︎ GitLab: deploy token or your own OAuth application“If it's relying on an SSH key, this means the repository was not set up using the native GitLab integration”
↩︎ GitLab: deploy token or your own OAuth application“dbt will not read repos associated with a user.”
↩︎ Exam trap 3“Once the admin completes those steps, dbt developers need to:”
↩︎ Checkpoint“Only users with maintainer permissions can set up repository connections.”
↩︎ Checkpoint - 5.
“which will be used to power headless actions in dbt such as deployment runs and CI.”
↩︎ Azure DevOps: service principal and personal links“We recommend setting up a separate Entra ID application than used for SSO.”
↩︎ Azure DevOps: service principal and personal links“Copy the first Redirect URIs value which looks like https://<YOUR_ACCESS_URL>/complete/azure_active_directory and does NOT end with service_user.”
↩︎ Azure DevOps: service principal and personal links“for the Entra ID application to work properly, you must select Multitenant.”
↩︎ Checkpoint - 6.
“you need to link your dbt profile to Azure DevOps, which provides an extra layer of authentication.”
↩︎ Azure DevOps: service principal and personal links