What you will be able to do
- Choose between a native integration, a git clone import and a managed repository for a dbt project, based on the git provider and the dbt plan
- Import a repository by SSH clone URL and install the dbt-generated deploy key with the right access on GitHub, GitLab, BitBucket, Azure DevOps or AWS CodeCommit
- Recognise the requirements and limits of native connections, such as GitHub repository name case, GitLab group and maintainer rules, and the lack of Azure DevOps Server support
- Disconnect and reconnect a project's repository to restore CI triggers or upgrade a git clone connection to a native one
Key concept
Repository connection method — Each dbt project is attached to its git repository through one method: a native provider integration, an import by SSH clone URL, or a managed repository. That choice decides which git features the project can use later, especially CI jobs triggered by pull requests and run statuses sent back to the provider.
1.Three ways to give a dbt project its repository
Every dbt project reads its code from a git repository, and how you attach that repository decides what the platform can do with it later. You set the connection on the project itself. In Account settings, go to Projects, select the project, and use Configure repository. There are three routes. A native integration works with GitHub, GitLab or Azure DevOps. A git clone import works with any host you can reach over SSH. A managed repository is hosted by dbt for you.
Use the native route whenever your provider offers one. With a native integration you can set up CI jobs directly in dbt. A git clone import works with any host, but it gives up features that need a tight integration with the provider. The clearest example is dbt writing run statuses back onto a GitHub pull request.
| Git provider | Native dbt integration | Automated CI job | Git clone | Plans for the native integration |
|---|---|---|---|---|
| GitHub | Yes | Yes | Yes | All dbt plans |
| GitLab | Yes | Yes | Yes | All dbt plans |
| Azure DevOps | Yes | Yes | Yes | Enterprise, Enterprise+ (Starter and Developer can connect with a deploy key but cannot configure automated CI jobs) |
| BitBucket, AWS CodeCommit and other providers | No | No | Yes | Not applicable: set up CI/CD with custom pipelines |
Your dbt plan shapes the choice in three places, not one:
- Azure DevOps: the native integration needs Enterprise or Enterprise+. A Starter or Developer account can still develop against an Azure DevOps repository by importing it with a deploy key, but it gets no automated CI jobs. - GitHub: the shared dbt GitHub App reaches github.com only. An organisation on a ghe.com domain (cloud-managed, yet still out of reach), on GitHub Enterprise Server, or on EU-hosted GitHub needs a custom GitHub application, which Enterprise and Enterprise+ accounts can register. On other plans the route is an import by git URL, which supports fewer git features. - GitLab: Starter and Developer plans share a single deploy token, while Enterprise and Enterprise+ can bring their own GitLab OAuth application.
Providers with no native integration at all, such as BitBucket and AWS CodeCommit, are always imported by git clone. For those, CI comes from calling the dbt Administrative API, or from a custom pipeline that runs on the provider's side.
A managed repository is the option for a team that has no repository yet. dbt hosts it, you can export it later if you move to your own git host, and it lets you try dbt without creating anything first. dbt Labs advises against using one in production because it has no pull requests. To move an existing project onto a managed repository, first disconnect the repository it already has.
The project-level connection is separate from each developer's personal link. Developers link their own git accounts under Personal profile > Linked accounts. That profile-level step, and the account-level app setup behind it, are covered in [git provider integrations](lesson:2.2).
Checkpoint 1 of 8· Check yourself
A team keeps its dbt project in BitBucket and wants a dbt job to run whenever a pull request is opened. What can they actually set up?
BitBucket has no native dbt integration, so the repo is imported by git clone. Automated CI then has to come from outside dbt, for example by calling the Administrative API.
“leverage the dbt Administrative API to trigger a CI job to run.”Source: docs.getdbt.com
Checkpoint 2 of 8· Exam question
An engineering team's git provider is GitHub Enterprise Cloud (ghe.com), and their dbt Cloud account is not on a Single Tenant deployment. When they try to use the native GitHub App integration, the provider does not appear as connectable. What should they do instead?
Correct answer: A — Import the repository using the generic git URL method with an SSH deploy key, since native GitHub App connectivity is not available for ghe.com outside Single Tenant accounts.
- A. GitHub Enterprise Cloud (ghe.com) is only reachable through the native GitHub App on Single Tenant dbt Cloud accounts, so standard accounts fall back to the generic git URL and deploy key workflow. This gives full clone and push access even without native CI triggering.
- B. There is no elevated-scope reinstall path that unlocks ghe.com support on a standard account; the limitation is architectural, tied to Single Tenant hosting, not app permission scopes. Reinstalling the app would not change the underlying constraint.
- C. Single Tenant status applies to the entire dbt Cloud account's infrastructure and cannot be toggled per warehouse connection, and warehouse connections are unrelated to git provider support. This mixes up two independent account settings.
- D. The dbt GitHub App does not use a client ID that GitHub support can selectively whitelist per tenant; the ghe.com restriction is a dbt Cloud hosting-tier limitation, not a GitHub-side allowlist issue. Support cannot override this from GitHub's side.
2.Importing a project by SSH clone URL and deploy key
A git clone import accepts any valid git URL that points to a dbt project, as long as it is an SSH URL. If you paste an https:// address, dbt cannot clone the repository. Most providers show the SSH URL under Code > Clone > SSH in SCP style, with a colon between the host and the repository path. dbt accepts that form exactly as shown.
git@github.com:organization/repo-name.git
user@custom-host.example.com:organization/repo-name.gitThe ssh:// form is equally valid. To convert an SCP-style URL, add the scheme in front and replace the colon after the host with a slash.
After the import, dbt generates a Deploy Key. Nothing can be cloned until that key is installed on the git host. To find it, go to Account settings > Projects, select the project, click the Repository link, and copy the key from the Deploy Key section. The key must allow read and write access to the repository. Each project gets its own key, even when two projects point at the same repository. A second project on a shared repo therefore means a second key on the provider. On CodeCommit, only the public key generated by dbt works. A key generated anywhere else is rejected.
Checkpoint 3 of 8· Check yourself
Two dbt projects were imported by git URL from the same repository, and the first project's deploy key is already installed on the git host. What does the second project need?
dbt generates a different deploy key for every project, even when projects share a repository, so each key has to be supplied to the git provider.
“Each dbt project will generate a different deploy key when connected to a repo, even if two projects are connected to the same repo.”Source: docs.getdbt.com
Where you paste the key depends on the provider. GitHub and GitLab also offer native dbt applications that enable CI, so a deploy key there is the fallback for repositories that cannot use that route:
- GitHub: the repository's settings page, under the Deploy keys tab. Tick Allow write access. - GitLab: the SSH keys tab under User Settings. - BitBucket: the SSH keys tab under Personal Settings, preferably on a service account. BitBucket ties every commit to the email address of the account that holds the key. - Azure DevOps: SSH public keys under User Settings, ideally on a dedicated service user, so that permission changes to a real person do not break the connection. The reasoning is the same as for any [service account](lesson:3.2).
Checkpoint 4 of 8· Match them up
Match each git provider to the place where its dbt deploy key is added
Tap a term, then the definition that fits it.
On GitHub the key is attached to the repository. On GitLab, BitBucket and Azure DevOps it is attached to an account in the user's settings.
“To add a deploy key to a GitHub account, navigate to the Deploy keys tab of the settings page in your GitHub repository.”Source: docs.getdbt.com
AWS CodeCommit needs more setup than the other providers:
1. Create an IAM user for dbt with the AWSCodeCommitPowerUser permission.
2. Paste the repository's SSH URL into the Git Clone tab in dbt.
3. Upload the dbt deploy key as that IAM user's SSH public key.
4. Send the resulting SSH key ID to dbt Support, who complete the connection.
CodeCommit's default branch is master, so set the Development environment to default to master as a [custom branch](lesson:3.7). Without a review step, users can merge straight into the default branch. Setting the Pull request URL field on the Repository details page makes the Studio IDE prompt developers to open a PR after they commit. The repository name in that URL is case sensitive.
When a git clone import fails, there are three usual causes:
- An invalid URL: the path is wrong, the repo does not exist, or the URL uses HTTP. - An outage at the git provider. - SSH access that is not set up correctly, for example a missing deploy key, a key without write access, or an organisation policy that blocks deploy keys.
Rule out all three before you contact dbt Support.
Checkpoint 5 of 8· Exam question
A team imported a project by git URL and pasted the generated deploy key into their GitHub repository's deploy keys settings, but dbt Cloud jobs still fail when attempting to push commits made through CI. Which single configuration change most likely resolves this?
Correct answer: A — Re-add the deploy key with the 'Allow write access' checkbox enabled, since a read-only deploy key permits cloning but blocks any push back to the repository.
- A. A deploy key added without write access only allows dbt Cloud to clone the repository, not push to it, so any workflow step that commits back will fail until the key is re-added with write access enabled. This is the documented cause of exactly this symptom.
- B. Deploy keys generated for a git URL import do not expire after a single clone; they remain valid for repeated clone and push operations as long as they stay configured with the correct access level. This misattributes the failure to a nonexistent expiry behavior.
- C. Branch protection rules govern who can push to protected branches directly, but the described failure is about the deploy key's own access level, not branch-level force-push policy. Adjusting protection rules would not address a read-only key.
- D. Git URL imports in dbt Cloud clone exclusively over SSH, and HTTPS URLs are explicitly unsupported for this method. Converting the URL format would break the clone rather than fix the push permission issue.
Sources1
3.What a native connection adds, and its limits
A native connection replaces the deploy key with an authenticated link to the provider. You import repositories with a couple of clicks, dbt clones over HTTPS instead of SSH, and opening a pull request (a merge request on GitLab) triggers CI builds. GitLab handles part of this for you when the repository is configured. It registers a webhook that triggers dbt pipeline jobs. It also creates a project access token that dbt uses to send CI job statuses back to GitLab, and dbt refreshes that token automatically.
Each provider has its own requirements:
- GitHub: the repository name you enter in the UI, API or Terraform provider must use exactly the same case as the GitHub URL. If the URL is github.com/my-org/MyRepo, enter MyRepo. Entering myrepo causes cloning errors or failed jobs.
- GitLab: you need a GitLab Premium or Ultimate account, and the repository must belong to a GitLab group. dbt does not read repositories owned by an individual user. The person connecting it must also be a maintainer of the repository.
- GitLab on dbt Starter or Developer plans: dbt uses a single deploy token, created by the first user who connects the repository. Every commit from the Studio IDE appears to come from that token, and GitLab push rules may reject those pushes.
The shared dbt GitHub App reaches github.com only. A GitHub Enterprise Cloud organisation on a ghe.com domain, GitHub Enterprise Server and GitHub with EU data residency all sit outside its reach. On Enterprise and Enterprise+ plans, register a custom GitHub application and point dbt at it; one custom application serves the whole dbt account, not one per project. On other plans, import the project by git URL and accept the smaller feature set.
Installing the shared GitHub App takes rights on both sides. You must be a GitHub organization owner, and that owner also needs Owner or Account Admin permissions in dbt. The app is assigned read access to metadata and read and write access to Checks, Commit statuses, Contents (Code), Pull requests, Webhooks and Workflows.
A repository can look connected while running over the generic route. In the GitLab repository details, a native import shows a deploy_token clone strategy. If the strategy is an SSH key, the repository was imported by git clone. It has none of the native benefits until you reconnect it through the integration.
Azure DevOps sets the clearest limit. The native integration supports Azure DevOps cloud accounts only, on Enterprise and Enterprise+. It does not support Azure DevOps Server (on-premise). An organisation running Azure DevOps Server connects by importing the project by git URL instead.
Checkpoint 6 of 8· Check yourself
An Enterprise+ customer hosts its repositories on Azure DevOps Server in its own data centre. How should the dbt project be connected?
The native Azure DevOps integration supports cloud accounts only, regardless of plan, so an on-premise server is connected by git clone.
“Instead, you can import a project by git URL to connect to an Azure DevOps Server.”Source: docs.getdbt.com
Checkpoint 7 of 8· Exam question
Which of the following permissions does the dbt GitHub App request when a GitHub organization owner installs it to connect a repository? (Select all that apply.)(Select 2)
Correct answers: A, B — Read and write access to pull requests and commit statuses; Read and write access to repository contents and webhooks
- A. The dbt GitHub App requests read and write access to pull requests and commit statuses so it can post CI check results and update PR status when jobs run. This is one of the core permissions granted during installation.
- B. The app also requests read and write access to repository contents and webhooks, which lets it clone code and auto-manage the webhook that triggers CI jobs on pull request events. This pairs with the pull request and status permissions.
- C. The app does not request administrative access to billing or account settings; its permission scope is limited to the repository-level actions needed for cloning and CI, not organization administration. This overstates the app's footprint.
- D. The app does not request organization member email addresses; that data is unrelated to cloning repositories or running CI checks. This is not part of the documented permission set.
4.Disconnecting and reconnecting a project's repository
Disconnecting and reconnecting the repository repairs some connection faults, but look for the cause first.
- GitLab, CI not triggering: the webhook is usually missing or wrong. In Settings > Webhooks, confirm it is enabled and has the correct URL and secret. - Azure DevOps, CI not triggering: confirm the repository's service hooks still exist and point to your dbt account. Then confirm that the identity dbt uses to reach Azure DevOps can still reach the repository. The native integration connects as either a service principal (the recommended method) or a service user (the legacy method), so check whichever one your integration was set up with.
If those checks pass and CI still does not fire, reconnect the repository.
Reconnecting is also documented as the alternative to accepting new permissions in GitHub when dbt reports that the account needs to accept the latest dbt GitHub App permissions. For GitLab, it is how you move a repository that was imported by git clone onto the native integration. The sequence is the same each time:
1. In Account settings > Projects, select the project. 2. Click the Repository link, then Edit, then Disconnect. 3. Click Confirm Disconnect. 4. Click Configure Repository and connect the same repository.
Checkpoint 8 of 8· Check yourself
On Azure DevOps, the repository's service hooks exist and point to your dbt account, and the service principal still has access, yet opening a pull request triggers no CI job. What is the documented next step?
Once the service hooks and the repository access check out, the remaining fix is to disconnect and reconnect the same repository.
“If those look fine, disconnect and reconnect the repository:”Source: docs.getdbt.com
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A git clone import works with the HTTPS URL copied from the browser, because native integrations clone over HTTPS.Why is that wrong?
Git clone imports work only over SSH, using the git@ or ssh:// form. HTTPS cloning applies only to the native integrations.
Covered in Importing a project by SSH clone URL and deploy key
2.Two dbt projects pointing at the same repository can share the deploy key already installed for the first project.Why is that wrong?
Each project generates its own deploy key, so every key has to be added to the git provider.
Covered in Importing a project by SSH clone URL and deploy key
3.An Enterprise+ plan unlocks the native Azure DevOps integration for an on-premise Azure DevOps Server.Why is that wrong?
The native integration supports Azure DevOps cloud accounts only. Azure DevOps Server is connected by importing the project by git URL.
4.Entering a GitHub repository name in lowercase is harmless, because repository names are case-insensitive.Why is that wrong?
The name must match the case in the GitHub URL exactly. Otherwise cloning or jobs fail.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“If your git provider has a native dbt integration, you can seamlessly set up continuous integration (CI) jobs directly within dbt.”
↩︎ Three ways to give a dbt project its repository“Some features of dbt require a tight integration with your git host, for example, updating GitHub pull requests with dbt run statuses.”
↩︎ Three ways to give a dbt project its repository“Organizations on the Starter and Developer plans can connect to Azure DevOps using a deploy key.”
↩︎ Three ways to give a dbt project its repository“Configure this Deploy Key to allow read and write access to the specified repositories.”
↩︎ Importing a project by SSH clone URL and deploy key“be sure to check the Allow write access checkbox.”
↩︎ Importing a project by SSH clone URL and deploy key“If you use GitHub, you can import your repo directly using dbt's GitHub Application.”
↩︎ Importing a project by SSH clone URL and deploy key“To preserve account security, use a service account to add the BitBucket deploy key”
↩︎ Importing a project by SSH clone URL and deploy key“We recommend using a dedicated service user for the integration”
↩︎ Importing a project by SSH clone URL and deploy key“Any other key that has been generated outside of dbt will not work.”
↩︎ Importing a project by SSH clone URL and deploy key“CodeCommit uses master as its default branch”
↩︎ Importing a project by SSH clone URL and deploy key“The URL is invalid: Confirm the repo path is correct, the repo exists, and you are using an SSH clone URL”
↩︎ Importing a project by SSH clone URL and deploy key“Importing your project by a URL prevents you from using these features.”
↩︎ Key concept“Use an SSH clone URL for your repo. dbt supports both common SSH formats:”
↩︎ Exam trap 1“Each dbt project will generate a different deploy key when connected to a repo, even if two projects are connected to the same repo.”
↩︎ Exam trap 2“leverage the dbt Administrative API to trigger a CI job to run.”
↩︎ Checkpoint“Use an SSH clone URL for your repo. dbt supports both common SSH formats:”
↩︎ Prediction“Each dbt project will generate a different deploy key when connected to a repo, even if two projects are connected to the same repo.”
↩︎ Checkpoint“To add a deploy key to a GitHub account, navigate to the Deploy keys tab of the settings page in your GitHub repository.”
↩︎ Checkpoint - 2.
“hosted on a ghe.com domain, the shared dbt GitHub App can't reach it.”
↩︎ Three ways to give a dbt project its repository“Enterprise and Enterprise+ accounts can connect by registering a custom GitHub application instead.”
↩︎ Three ways to give a dbt project its repository“On other plans, connect using a Git URL, which supports fewer Git features.”
↩︎ Three ways to give a dbt project its repository“Clone repos using HTTPS rather than SSH.”
↩︎ What a native connection adds, and its limits“The shared dbt GitHub App is hosted per region, so it can only reach repositories on github.com.”
↩︎ What a native connection adds, and its limits“You can use one GitHub application per dbt account, not one per project.”
↩︎ What a native connection adds, and its limits“You must be a GitHub organization owner to install the application.”
↩︎ What a native connection adds, and its limits“Your GitHub organization owner also needs Owner or Account Admin permissions in dbt platform.”
↩︎ What a native connection adds, and its limits“Read and write access to Commit statuses Read and write access to Contents (Code) Read and write access to Pull requests”
↩︎ What a native connection adds, and its limits“the repository name must exactly match the case used in the GitHub URL to avoid cloning errors or job failures.”
↩︎ Exam trap 4 - 3.
“dbt Starter and Developer plans use a single GitLab deploy token created by the first user who connects the repository”
↩︎ Three ways to give a dbt project its repository“Registers a webhook that triggers pipeline jobs in dbt.”
↩︎ What a native connection adds, and its limits“which sends the job run status back to GitLab using the dbt API for CI jobs”
↩︎ What a native connection adds, and its limits“You must have a GitLab Premium or Ultimate account.”
↩︎ What a native connection adds, and its limits“Your repository is in a Gitlab group you have access to. dbt will not read repos associated with a user.”
↩︎ What a native connection adds, and its limits“Only users with maintainer permissions can set up repository connections.”
↩︎ What a native connection adds, and its limits“dbt Starter and Developer plans use a single GitLab deploy token created by the first user who connects the repository”
↩︎ What a native connection adds, and its limits“The repository must be reconnected in order to get the benefits described above.”
↩︎ What a native connection adds, and its limits“The webhook registration is configured with the correct URL and secret.”
↩︎ Disconnecting and reconnecting a project's repository“The repository must be reconnected in order to get the benefits described above.”
↩︎ Disconnecting and reconnecting a project's repository - 4.
“dbt Labs recommends against using a managed repository in a production environment.”
↩︎ Three ways to give a dbt project its repository“If the project already has a repository set up, you need to edit the repository settings and disconnect the existing repository.”
↩︎ Three ways to give a dbt project its repository - 5.
“Connecting an Azure DevOps cloud account is available for organizations using the dbt Enterprise or Enterprise+ plans.”
↩︎ What a native connection adds, and its limits“Confirm the Azure DevOps service hooks for the repository still exist and point to your dbt account.”
↩︎ Disconnecting and reconnecting a project's repository“Confirm your service principal or service user still has access to the repository.”
↩︎ Disconnecting and reconnecting a project's repository“Service principal (recommended)”
↩︎ Disconnecting and reconnecting a project's repository“Instead, you can import a project by git URL to connect to an Azure DevOps Server.”
↩︎ Exam trap 3“Instead, you can import a project by git URL to connect to an Azure DevOps Server.”
↩︎ Checkpoint“If those look fine, disconnect and reconnect the repository:”
↩︎ Checkpoint - 6.https://docs.getdbt.com/faqs/Git/github-permissionsOfficial docs
“Return to your Project details page and reconnect your repository by clicking the Configure Repository link.”
↩︎ Disconnecting and reconnecting a project's repository