Skip to content

Trunk-Based Development

Home › Explanation › Continuous Delivery › Workflow › Trunk Based Development

Introduction

Trunk-Based Development is the branching strategy and workflow that enables Continuous Integration and Continuous Delivery.

Instead of long-lived topic branches that defer integration, Trunk-Based Development emphasizes frequent integration to a single main branch (trunk), enabling rapid feedback and reducing merge conflicts.

This approach is fundamental to achieving:

  • Continuous Integration: All developers integrate to trunk at least daily
  • Continuous Delivery: Head of trunk is always in a releasable state
  • Fast feedback: Issues detected within minutes, not weeks
  • Reduced risk: Small, incremental changes are easier to validate and rollback

Core Principles

1. Single Source of Truth

Principle: There is only ever one meaningful version of the code: the current one.

  • The main branch (trunk) is the only source of truth
  • The HEAD of main is the current version
  • All changes integrate to main frequently (at least daily)

Why this matters: Eliminates confusion about which version is the release candidate, enables continuous delivery, and provides clear traceability.

Anti-pattern: Long-lived feature branches that become "alternative versions" of truth.

2. Branch Very Briefly

Principle: At any given time, there are only 3 active branch types: trunk, topic branches, and release branches.

  • Topic branches live for hours or at most 1-2 days
  • Changes are kept small and focused
  • Branches are deleted immediately after squash merging

Why this matters: Prevents integration drift, enables continuous integration, reduces merge conflicts.

Anti-pattern: "Feature branches" that live for weeks, accumulating hundreds of changes.

3. Small, Incremental Changes

Principle: Work in small batches that are continuously integrated.

  • Each change is a small, logical increment
  • Large features broken into deployable pieces
  • Feature hiding used for incomplete features

Why this matters: Easier to review, faster to validate, lower risk.

Anti-pattern: Massive "big bang" merges making review impossible and rollback risky.

4. Continuous Integration to Trunk

Principle: Integrate at least daily, preferably multiple times per day.

  • Developers pull from main frequently
  • Push changes as soon as they pass local validation
  • Pipeline validates every trunk commit

Why this matters: Early detection of integration issues, maintains releasable trunk.

Anti-pattern: Developers working in isolation for days/weeks before attempting integration.

5. Branch by Abstraction

Principle: Instead of branching for a feature, create an abstraction in code that can be toggled off.

This technique is a key enabler for continuous integration. Many developers are trained to hide new features in branches, but this conflicts with frequent integration.

See Feature Hiding for implementation strategies.

Daily Development Flow

Typical workflow:

  1. Sync with trunk: git pull origin main
  2. Create topic branch: git checkout -b feature/short-description
  3. Make small changes: Keep small, optimally one logical change
  4. Integrate regularly: Pull from trunk every few hours
  5. Push and create merge request: Triggers Stage 2-3 validation
  6. Address review feedback: Push additional commits
  7. Squash merge to trunk: One topic branch = one trunk commit

Key command:

gh pr merge --squash --delete-branch

Conflict Resolution

Prevention is key: Pull from trunk frequently (every few hours), keep changes small, and integrate hourly to daily.

When conflicts occur: pull latest, resolve locally, rebase main onto your local branch if complex.

Next Steps

References

External

Tutorials | How-to Guides | Explanation | Reference

You are here: Explanation — understanding-oriented discussion that clarifies concepts.