dbt Branching Strategy: When to Use Trunk-Based vs Release Branches

dbt ties environments and deployments to Git branches, so your branching strategy directly affects quality, velocity, and risk.

This article starts from trunk-based development (main-centered) as the default, then walks through when a release branch is needed, design patterns, CI/testing, schema design, and selectors (state:modified) in concrete detail.

Fundamentals and Terminology: Branches and Environments in dbt

In dbt, the Git branch is the primary switch that decides which code will run. In dbt Cloud, a deployment Environment is tied to a single Git branch, and jobs execute against that branch's code. The CLI works the same way — whichever branch you have checked out is what dbt commands run against.

Trunk-based (main-centered) merges small, frequent changes into main and relies on PRs for quality. A release branch bundles changes at a point in time into a fixed "release unit," making it easier to freeze, validate, roll out incrementally, and roll back.

• Goal of trunk-based: ship continuously in small diffs (low risk, short lead time)
• Goal of release branches: bundle large or externally visible changes for managed delivery (visibility, easy rollback)
• Stable dbt features in play: state:modified selection, deferred execution, tests/contracts, PR builds (dbt Cloud)

Implementing Trunk-Based Development (dbt Cloud and CLI)

The basic flow is: feature branch → PR review and CI → merge into main → main deploys to production. PR CI uses slim CI (state comparison) to quickly validate only the diff and its dependencies. Deployment is centralized in a production Environment/job that tracks the main branch.

To minimize the gap between production and PR builds, use defer to reference production artifacts (the previous manifest/Run Results), avoiding rebuilds of unchanged models while still validating dependency integrity.

• Develop on feature/*. When the PR is opened, run dbt build via slim CI
• On the PR, check tests (schema and data), contracts, and exposure impact
• After merging to main, the main-pinned production job runs dbt build (state:modified+ for differential deploys)

Standard trunk-based flow (PR CI → main deploy)

Minimal slim CI example (CLI, run on PRs)

dbt deps
# Reference the previous production artifacts (location depends on your setup: S3/GCS/DBFS/local, etc.)
dbt build \
  --select state:modified+ \
  --state path/to/prod_artifacts \
  --defer

When to Use a Release Branch and How to Design It

For day-to-day operations, trunk-based is enough. But a release branch is useful when: you need a bulk cutover aligned with external data sharing or BI publishing; regulators or auditors strongly require reproducibility of "this version"; you have a long-running backfill or schema migration that needs phased rollout; or you need a code freeze during a busy season.

The design principle: once you cut release/*, only pull in the minimum necessary changes, run PR review/CI on the release branch, and either point the production Environment at it temporarily or apply it first in a canary Environment before cutting over. Cut hotfixes from the release branch, cherry-pick them, and back-merge into main to keep drift in check.

• Run release/* as short-lived and purpose-limited (long-lived release branches easily become technical debt)
• Where possible, isolate backfills and migrations in dedicated jobs and keep only minimal control on the release branch
• After cutover, back-merge into main quickly to eliminate drift

Release branch basic operations (example)

# Create a temporary release branch
git switch -c release/2024w42

# Merge only the necessary PRs (keep scope minimal)
# ... code review / merge ...

# Temporarily point the dbt Cloud production Environment at release/2024w42
# or apply changes first in a canary Environment

# Hotfix
git switch -c hotfix/bug-on-release release/2024w42
# After fixing, merge into the release branch and roll out to production
# Back-merge into main to eliminate drift

Schema and Environment Isolation (How dev/stg/prod Map to Branches)

It is common in dbt to separate environments by schema within the same database. Let branches decide "which code runs" and environments decide "where it deploys." A per-user schema in dev, a shared schema in stg/qa, and a fixed schema in prod is the easiest split to manage.

Align schema naming with your branching strategy by using target.name and custom schemas consistently. For expand/contract migrations, keep the old column around for a transition period to preserve compatibility — this lets you proceed safely whether or not you use a release branch.

• Use a user_ prefix in dev to avoid collisions; pin prod to a stable name
• Control per-environment execution of seeds/snapshots via tags
• Always enable exposures and contracts in prod, and validate them on the PR

A generate_schema_name example (isolating schemas by environment)

{% macro generate_schema_name(custom_schema_name, node) -%}
  {% if target.name == 'prod' %}
    {{ custom_schema_name or 'analytics' }}
  {% else %}
    {{ target.name }}__{{ custom_schema_name or 'analytics' }}
  {% endif %}
{%- endmacro %}

CI/CD and Quality Gates: Combining state Selectors, defer, and Tests

The core of slim CI is state comparison. By diffing against the previous production artifact, it builds and tests only the changed models and their downstream. Combining this with defer resolves unchanged upstream models "as if they exist," dramatically speeding up PR builds.

Even during release-branch operations, use the same selectors and defer on the release branch, and separate migration jobs (backfills) by tag. Design CI so that contracts and tests (unique/not_null/relationships) always run on the PR.

• Define state selectors in selectors.yml and reuse them
• Contracts: roll out backward-incompatible changes in stages with expand → dual-write → contract
• Run migration jobs in isolation by tagging them, for example tags: [migrate, backfill]

selectors.yml and example commands

# selectors.yml
selectors:
  - name: pr_modified
    definition:
      method: state
      value: modified
      children: true

# Example (PR CI)
dbt build --select @pr_modified --state path/to/prod_artifacts --defer

# Example (production)
dbt build --select state:modified+ --state path/to/prod_artifacts

Exam-Prep Highlights and Common Pitfalls

The Analytics Engineer exam is less about branching strategy itself and more about PR-centric development, when to use state/defer, quality gates via contracts/tests, and backward-compatible migrations (expand/contract). For release branches, the key is recognizing the exceptional cases where they are genuinely needed.

Typical mistakes include letting long-lived release branches drift far from main, mixing backfills into the main pipeline so PRs cannot pass, and breaking downstream with schema changes. All of these can be avoided through small diffs, tag-based isolation, state usage, and phased migrations.

• Default to trunk-based. Use release branches only for limited cases: audit, external publishing, freezes, or large-scale migrations
• Use state:modified together with defer in PR CI to validate only the diff and its downstream
• Roll out backward-incompatible changes in stages via expand/contract, and respect contracts

Minimal contracts and tests example

models:
  - name: fct_orders
    config:
      contract: true
    columns:
      - name: order_id
        data_type: int
        tests:
          - unique
          - not_null
      - name: customer_id
        data_type: int
        tests:
          - relationships:
              to: ref('dim_customers')
              field: customer_id

Check Your Understanding

Frequently Asked Questions