What you will be able to do
- Configure an environment to run on a custom branch or tag instead of the repository's default branch
- Explain how a custom branch changes branch protection and PR targets in the development environment
- Explain which code a deployment environment clones for its jobs when a custom branch is set
- Fix the IDE's git rev-list error by changing an environment's custom branch setting
Key concept
Custom branch (per environment) — An environment-level git setting that replaces the repository's default branch with a named branch or tag. In development it becomes the protected branch that developers branch from and open PRs against. In deployment it is the branch that environment's jobs clone and run.
1.What the custom branch setting overrides
Every dbt environment answers one question that is easy to overlook: which version of the code should run? Along with the dbt version and the warehouse connection, an environment fixes the version of your code to execute. Unless you change it, the answer is the repository's default branch, usually main, for every environment in the project.
The custom branch setting is how you give one environment a different answer. It sits in the environment's General Settings, which development and deployment environments both have. You tick Only run on a custom branch and enter a value in Custom branch. That value can be a branch name such as develop, or a tag. Tags are easy to forget: an environment can be pinned to a tag as well as to a moving branch.
The setting belongs to the environment, not to the project and not to a single job. Every job in an environment runs on that environment's branch. If two sets of jobs need different code, they need two environments, and [creating a deployment environment](lesson:3.5) is how you get the second one. The same checkbox also behaves differently depending on the environment type, which the next two sections cover.
Checkpoint 1 of 7· Put it in order
You want an existing environment to use the develop branch of the connected repository. Put the steps in order.
- 1.Select Only run on a custom branch in General settings
- 2.Enter develop as the name of your custom branch
- 3.Click Save
- 4.Go to the environment and click Settings > Edit
You open the environment for editing, turn the custom branch option on, name the branch, and then save. The branch field only matters once the checkbox is selected.
“Enter develop as the name of your custom branch.”Source: docs.getdbt.com
2.Custom branches in the development environment
A project has exactly one development environment, and it drives the Studio IDE and the dbt platform CLI. Without a custom branch, the primary branch is protected there. Developers can open it, edit, format and lint files, and run dbt commands against it, but the Studio IDE won't let them commit to it. When they're ready, they commit their changes to a new branch.
Setting a custom branch moves that protection to the new branch. In the development environment, the custom branch decides which branch developers create their branches from and open PRs against. Developers can still edit and run dbt on it, but they can't commit to it, and dbt prompts them to commit to a new branch instead. A team that works on develop and promotes to main later gets exactly this: every feature branch starts from develop, and every PR from the IDE targets develop.
The catch is that only one branch can be protected. Once develop is the custom branch, main loses its protection in dbt. If main still has to be locked down, set up branch protection rules in the git provider. That rule lives outside dbt, so changing the environment's custom branch later won't remove it.
Checkpoint 2 of 7· Check yourself
After the development environment's custom branch is set to develop, a developer edits a model while on develop in the Studio IDE and runs it successfully. What happens when they try to commit?
On a protected custom branch you can edit, lint and run dbt commands, but you can't commit. dbt asks you to commit to a new branch instead.
“You can directly edit, format, or lint files and execute dbt commands in your custom branch, but you cannot make commits to it.”Source: docs.getdbt.com
Checkpoint 3 of 7· Exam question
An administrator disables "Only run on a custom branch" on a deployment environment previously pinned to `hotfix/critical-patch`. What happens to the branch used for the next job run in that environment?
Correct answer: A — The next job run clones the repository's default branch, typically `main`, because dbt falls back to the default branch whenever no custom branch override is configured.
- A. This is correct because unchecking the custom branch option removes the override, and dbt reverts to cloning the repository's default branch for subsequent runs.
- B. This is incorrect because the environment does not cache the previous custom branch; once the override is disabled, it no longer applies to new runs.
- C. This is incorrect because no explicit override is required for a job to run; the repository's default branch is always the implicit fallback.
- D. This is incorrect because dbt job runs are non-interactive and never pause mid-run to ask which branch to clone.
3.Custom branches in deployment environments
Deployment environments have nobody committing to them, so the setting has a different effect there. Before a job runs, dbt clones the project from the connected repository, and by default it clones the default branch. A custom branch changes which branch is cloned for that environment's job runs. It controls what code reaches the warehouse, not where PRs go.
That makes the setting the standard way to run a branch other than main on a schedule. Two cases show up often:
- Release train. A QA deployment environment has its branch set to qa. Feature work is merged into qa and tested there, and a release manager later opens a PR from qa into main.
- dbt version upgrade. A temporary deployment environment is set to the custom branch dbt-version-upgrade and the newer dbt version. A copy of a production job runs there before anything is merged into main.
In both cases production keeps running from main, and the branch under test runs in its own environment.
The development and deployment settings work independently. In the release-train setup, once the development environment's branch points at QA, the IDE's create-PR button opens PRs against the QA branch instead of main. A QA deployment environment set to qa doesn't do that by itself, because it only decides what its jobs clone. The environment's branch also acts as the base branch for its merge-triggered jobs, which run whenever a PR merges into it. How those jobs compare state belongs with [deferral between environments](lesson:3.8) and [self-deferral](lesson:4.10).
| Aspect | Development environment | Deployment environment |
|---|---|---|
| How many per project | 1 | Any number of General, one Staging, one Production |
| Without a custom branch | Default branch (usually main) is protected | Jobs clone the default branch |
| With a custom branch | Custom branch is protected; developers branch from it and open PRs against it | Jobs clone the custom branch |
| Effect on main | No longer protected by dbt; use git provider branch protection rules | Not cloned by this environment's jobs |
Checkpoint 4 of 7· Match them up
Match each configuration to its effect.
Tap a term, then the definition that fits it.
In development the custom branch sets the base and the PR target. In deployment it sets what jobs clone. dbt protects only one branch, so main needs git provider rules once another branch is protected.
“Deployment: determines the branch is cloned during job executions for each environment.”Source: docs.getdbt.com
Checkpoint 5 of 7· Exam question
A dbt Cloud admin manages a single project connected to one GitHub repository. They want production jobs to build from `main` while a separate QA deployment environment builds from `qa/release-candidate`. Is a single custom branch setting on the project sufficient to achieve this, or does each environment need its own setting?
Correct answer: A — Each environment needs its own custom branch setting, because the custom branch field is configured per environment rather than once for the entire project.
- A. This is correct because the custom branch override lives on each individual environment's settings, so achieving different branches per environment requires configuring the QA environment separately from production.
- B. This is incorrect because there is no project-wide branch setting that other environments inherit; each environment's git behavior is independent.
- C. This is incorrect because dbt does not infer branch names from environment names; the branch must be explicitly entered in the custom branch field.
- D. This is incorrect because deployment environments do not default to the development environment's branch; each deployment environment falls back to the repository's default branch unless it has its own override.
4.When the branch setting breaks the Studio IDE
A mismatch between the custom branch and the repository's real primary branch can lock developers out of the Studio IDE. A typical symptom is a git error when the IDE opens, such as fatal: ambiguous argument 'master..origin/main' from git rev-list master..origin/main --count. Usually the primary branch was renamed, for example from master to main, or dbt couldn't work out which branch is primary.
Both fixes start with disconnecting and reconnecting the repository on the Project Settings page, so dbt picks up the current primary branch name. The next step depends on what the environment settings show:
- No custom branch set: set the custom branch to master and refresh the Studio IDE.
- A custom branch already set: remove the custom branch and refresh the Studio IDE.
Either way, the custom branch field ends up matching a branch that actually exists in the repository. If the error persists after both steps, the next step is dbt Support.
Checkpoint 6 of 7· Check yourself
The Studio IDE fails to open with a git rev-list master..origin/main error. The development environment already has a custom branch filled in. After reconnecting the repository in Project Settings, what should you do?
When a custom branch is already set, the fix is to remove it so dbt uses the newly detected primary branch. Setting it to master is the fix when no custom branch was set. A project can only have one development environment anyway.
“In the Environment Settings, remove the custom branch and refresh the Studio IDE.”Source: docs.getdbt.com
Checkpoint 7 of 7· Exam question
An environment's settings panel shows the following fields: `Environment name: CI`, `Environment type: Deployment`, `dbt version: Versionless (latest)`, `Only run on a custom branch: unchecked`, `Custom branch: (blank)`. A CI job in this environment keeps building against `main` even though the team wants it to build against `feature/new-model` for every pull request. Which field must be changed to fix this?
Correct answer: A — Enable `Only run on a custom branch` and enter `feature/new-model` in the `Custom branch` field, since that combination overrides the repository's default branch for this environment.
- A. This is correct because checking the custom branch checkbox and populating the branch field is exactly what overrides the default branch for a deployment environment's jobs.
- B. This is incorrect because deployment environments fully support custom branch overrides; changing the environment type is unnecessary and would break the CI job's purpose.
- C. This is incorrect because the `dbt version` field controls the release track dbt runs on, such as versionless or a pinned version, and has nothing to do with which git branch is cloned.
- D. This is incorrect because dbt does not infer branches from environment names; the branch must be set explicitly through the custom branch field.
Sources6
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Setting develop as the custom branch leaves main protected as well, so both branches reject commits from the Studio IDE.Why is that wrong?
dbt protects only one branch. Once a custom branch is set, main is no longer protected, and you need branch protection rules in the git provider to keep it locked.
2.Once develop is the custom branch, developers can commit to it directly in the Studio IDE.Why is that wrong?
The custom branch becomes the protected branch. You can edit and run dbt on it but can't commit, and dbt prompts you to commit to a new branch.
3.Setting a custom branch on a deployment environment changes the branch developers branch from and open PRs against in the Studio IDE.Why is that wrong?
In a deployment environment the setting only decides which branch is cloned for that environment's job runs. The PR target comes from the development environment's setting.
Covered in Custom branches in deployment environments
4.The custom branch is chosen per job, so jobs in one environment can run different branches.Why is that wrong?
The setting lives in the environment's General Settings and applies to everything run in that environment. Different code needs a different environment.
Covered in What the custom branch setting overrides
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“By default, all environments will use the default branch in your repository (usually the main branch) when accessing your dbt code.”
↩︎ What the custom branch setting overrides“The version of your code to execute”
↩︎ What the custom branch setting overrides“Development: determines which branch in the Studio IDE or dbt platform CLI developers create branches from and open PRs against.”
↩︎ Custom branches in the development environment“Deployment: determines the branch is cloned during job executions for each environment.”
↩︎ Checkpoint - 2.
“Specify the branch name or tag”
↩︎ What the custom branch setting overrides“Development and deployment environments have slightly different effects.”
↩︎ What the custom branch setting overrides“Since the Studio IDE prevents commits to the protected branch, you can commit those changes to a new branch when you're ready.”
↩︎ Custom branches in the development environment“you need to set up branch protection rules in your git provider settings”
↩︎ Custom branches in the development environment“By default, dbt uses the default branch of your repository (commonly the main branch).”
↩︎ Custom branches in deployment environments“When specified, dbt executes models using the custom branch setting for that environment.”
↩︎ Key concept“Only one branch can be protected.”
↩︎ Exam trap 1“It makes the custom branch protected and enables you to create new development branches from it.”
↩︎ Exam trap 2“When running jobs in a deployment environment, dbt will clone your project from your connected repository before executing your models.”
↩︎ Exam trap 3“Select Only run on a custom branch under General Settings”
↩︎ Exam trap 4“Enter develop as the name of your custom branch.”
↩︎ Checkpoint“If you specify a custom branch, the primary branch is no longer protected.”
↩︎ Prediction“You can directly edit, format, or lint files and execute dbt commands in your custom branch, but you cannot make commits to it.”
↩︎ Checkpoint - 3.https://docs.getdbt.com/guides/set-up-ciOfficial docs
“Set its branch to qa as well.”
↩︎ Custom branches in deployment environments“Under this paradigm, that button will create PRs targeting your QA branch instead.”
↩︎ Custom branches in deployment environments - 4.
“creating a new deployment environment for testing, setting the custom branch to 'ON' and referencing your dbt-version-upgrade branch”
↩︎ Custom branches in deployment environments - 5.https://docs.getdbt.com/docs/deploy/merge-jobsOfficial docs
“Every time a PR merges (to a base branch configured in the environment) in your Git repo, this job will get triggered to run.”
↩︎ Custom branches in deployment environments - 6.
“Usually this error indicates that the "main" branch name has changed”
↩︎ When the branch setting breaks the Studio IDE“In the Environment Settings, set the custom branch to 'master' and refresh the Studio IDE.”
↩︎ When the branch setting breaks the Studio IDE“In the Environment Settings, remove the custom branch and refresh the Studio IDE.”
↩︎ Checkpoint