Trunk-Based Development

Status: Complete
Category: Delivery
Default enforcement: Soft
Author: PushBackLog team

Tags

• Topic: delivery, version-control, ci-cd
• Skillset: engineering, devops
• Technology: git
• Stage: execution, delivery

Summary

Trunk-based development (TBD) is a source-control workflow where all developers integrate their changes into a single shared branch (the trunk, or main) at least once per day. Short-lived branches (less than one day to a few days) are permitted; long-lived feature branches are not. TBD is the branching model that enables true continuous integration: if code is always integrated, it is always tested, always deployable, and divergence between developers is eliminated before it accumulates into merge conflicts.

Rationale

Long-lived branches are the enemy of continuous integration

The word “integration” in CI means merging code together. A team running daily CI builds but developing on week-long feature branches is not doing continuous integration — they are running a build server on code that has diverged significantly from what the rest of the team is working on. Merge day becomes fix-conflicts day. The bigger the batch, the bigger the blast radius.

Trunk-based development forces integration to happen continuously, in small increments. Conflicts are caught immediately when they are small and cheap to resolve. The trunk is always in a deployable state because every commit must pass CI before being accepted.

Feature flags decouple deployment from release

The objection to TBD is usually “but the feature isn’t ready.” Trunk-based development answers this by separating deployment (code is in production) from release (users can see it). Incomplete features are deployed behind a feature flag, dark-launched to zero users. When the feature is ready, the flag is turned on. This means the trunk can always be deployed, and features can be released independently of deployment.

Smaller batch sizes improve flow and quality

Lean and DevOps research (DORA metrics) consistently shows that the highest-performing engineering teams have the shortest integration intervals. Small commits are easier to review, easier to revert, clearer in intent, and create smaller failure blast radii. The correlation between trunk-based development and software delivery performance is one of the most robust findings in the DORA State of DevOps research.

Guidance

Branch lifetime guidelines

Commit frequency

• Developers should push to the trunk (or a short-lived branch) at least once per day
• Each push must pass all CI checks (lint, type-check, tests, build) before merge
• If CI is broken, the team stops and fixes it immediately — a broken trunk blocks everyone

Feature flags as the enabler

// Feature behind a flag — deployed but not released
if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
  return renderNewCheckout();
}
return renderLegacyCheckout();

Feature flag lifecycle:

1. Create flag (default: off) before writing the feature
2. Develop behind the flag in small increments, committing to trunk daily
3. Enable flag for internal users for testing
4. Gradually enable for real users (canary → 10% → 100%)
5. Remove the flag once fully rolled out — flag debt becomes maintenance debt

Integrating with PR-based workflows

TBD is compatible with pull requests if PRs are kept small and short-lived:

# Good TBD PR workflow
- PR opened
- CI runs (lint, test, build) — must pass
- One reviewer approves
- Merged to trunk within 24 hours
- No "waiting for the feature to be complete" — partial work is fine behind a flag

Single-person teams or trusted contributors may commit directly to trunk for small changes.

Comparison with Gitflow

Prerequisites for TBD

Trunk-based development works best when:

• CI is fast (< 10 minutes for a full build)
• Feature flags infrastructure is available
• The team has agreed on and enforces code quality standards (linters, tests)
• Code review is asynchronous and fast (not a blocking gate for hours)

Without fast CI and feature flags, teams often fall back to long-lived branches out of necessity. Invest in CI speed first.