# What is trunk-based development?

Trunk-based development is a branching model where developers merge small changes into one main branch at least daily, with no long-lived branches.

Last updated September 29, 2026, 8 min read

## Learning objectives

After reading this article you will be able to:

-   Define trunk-based development
-   Explain how feature flags hide unfinished work
-   Compare trunk-based development with Gitflow

## Related content

-   [What is CI/CD?](https://specstory.com/learning/ci-cd/ci-cd)
-   [What is continuous integration (CI)?](https://specstory.com/learning/ci-cd/continuous-integration)
-   [What is a merge queue?](https://specstory.com/learning/ci-cd/merge-queue)
-   [What is the difference between CI, continuous delivery and deployment?](https://specstory.com/learning/ci-cd/ci-vs-continuous-delivery-vs-deployment)
-   [What are required status checks?](https://specstory.com/learning/ci-cd/required-status-checks)

## What is trunk-based development?

Trunk-based development is a branching model in which each developer merges small changes into one shared branch, called the trunk, at least once a day. The trunk is the main branch of the repository, usually named `main` or `master`. Working branches typically last hours, not weeks, and the trunk stays ready to release.

Trunk-based development is the branching side of [continuous integration](https://specstory.com/learning/ci-cd/continuous-integration) (CI), the first half of [CI/CD](https://specstory.com/learning/ci-cd/ci-cd). DevOps Research and Assessment (DORA), the program behind the [DORA metrics](https://specstory.com/learning/ci-cd/dora-metrics), [defines CI](https://dora.dev/capabilities/trunk-based-development/) as trunk-based development plus fast automated tests that run after each change to the trunk. [Martin Fowler](https://martinfowler.com/articles/branching-patterns.html) notes that some people use the two terms as synonyms, and that "there isn't a consistent usage" for any difference between them.

DORA contrasts trunk-based development with feature branching, in which a developer works on a branch in isolation until the feature is complete. Merging daily means unfinished work reaches the trunk. Teams hide it behind a [feature flag](https://specstory.com/learning/glossary#feature-flag) that stays off until the work is finished. For large internal changes, some teams use branch by abstraction, which puts the old code and its replacement behind one interface and switches over when the replacement is ready.

## How does trunk-based development work?

One change reaches the trunk in these steps:

1.  A developer or a [coding agent](https://specstory.com/learning/ai-coding/coding-agent) starts a branch from the current trunk for one change. Small teams may push straight to the trunk instead.
2.  The author keeps the change small and runs the tests first.
3.  Unfinished work merges behind a feature flag that is off.
4.  The author opens a [pull request](https://specstory.com/learning/code-review/pull-request), CI runs the [required status checks](https://specstory.com/learning/ci-cd/required-status-checks), and a teammate reviews it the same day. DORA counts pair programming as a review.
5.  The change merges, and CI tests the trunk again. A failed build on the trunk is fixed or reverted before more work merges.
6.  Releases come from a tag or from a release branch cut from the trunk shortly before release.

Diagram: Short branches and a late release branch

Each working branch returns to main the same day, including unfinished work hidden behind a flag. In the model trunkbaseddevelopment.com describes, the release branch gets fixes only as copies from main and never merges back.

A feature flag is a setting that the code checks at runtime, so a team can turn a code path on or off, often without a deploy. The unfinished code can deploy to production and stay off there, and customers keep the old behavior until the team turns the flag on.

DORA's page says branches in trunk-based development "typically last no more than a few hours." The site [trunkbaseddevelopment.com](https://trunkbaseddevelopment.com/) calls them "short-lived feature branches" and allows them for [code review](https://specstory.com/learning/code-review/code-review) and CI checks when each belongs to one developer or a pair. In the site's model, a fix lands on the trunk first, with a test, and is copied to the release branch with `git cherry-pick`. The release branch is deleted later and never merged back.

## What is an example of trunk-based development?

Here is an illustrative example. Acme Co. sells furniture online. A developer at Acme asks a coding agent to "Let customers edit their delivery address during checkout." The work takes more than a day, so the agent puts it behind a flag:

```js
if (flags.isOn("checkout-address-edit", customer)) {
  showAddressEditor(order);
}
```

The change reaches customers in these steps:

1.  On Monday, the agent's first pull request adds the form behind the flag, which is off. It merges after a 20-minute review.
2.  On Tuesday, the second pull request adds the save path, still behind the flag. Customers still get the old checkout.
3.  CI runs the checkout tests twice, once with the flag off and once with it on. With the flag on, the cart test expects 2 items and receives 0. The address saved, but the cart emptied.
4.  The agent fixes the save path, both runs pass, and the change merges the same day.
5.  On Wednesday, the team turns the flag on for staff accounts, and then for customers.
6.  Two weeks later, the agent deletes the flag and the old checkout code in a pull request of its own.

The run with the flag on caught the broken save path before it merged, instead of on Wednesday, when the team turned the flag on for staff. This example is simplified. A real team would also try the checkout in a browser before turning the flag on for customers.

## What changes when a coding agent writes the code?

A coding agent can write a small change in minutes, so how long a branch stays open depends on review, not on writing. DORA warns against asynchronous code review, in which an author submits a change and starts another task while waiting. Handing work to an agent often follows that pattern, since the developer starts the next task while the agent works. With [parallel coding agents](https://specstory.com/learning/ai-coding/parallel-coding-agents), several of those pull requests can wait at once, each for hours or days.

Flags add a second problem. An agent that splits a feature across days puts each part behind a flag, and its tests can run with the flag in only one state. Code behind a flag that is off can then merge and never run in CI until someone turns the flag on. Pete Hodgson's [article on feature toggles](https://martinfowler.com/articles/feature-toggles.html) advises testing the flag settings expected in production, and the fallback with those flags off.

A practical adjustment is to review each agent's change as soon as the agent finishes it. Before the review, CI runs the tests twice, once with the change's flags on and once with them off.

## What are the limits of trunk-based development?

Trunk-based development has these limits:

-   **It depends on fast, reliable tests.** Daily merges keep the trunk working only when tests run before each merge and catch the break. With a slow or flaky suite, breaks reach the trunk, and a broken trunk holds up everyone who updates from it.
-   **A green trunk shows only that its checks passed.** Code behind a flag that is off runs in those checks only when CI turns the flag on. A [smoke test](https://specstory.com/learning/testing/smoke-testing) of each trunk build shows only that the software starts.
-   **Review has to keep pace.** DORA names an overly heavy review process as a common pitfall. When review takes hours or days, authors batch their work, and [pull request size](https://specstory.com/learning/code-review/pull-request-size) grows.
-   **Flags add code paths.** Each flag doubles the states a piece of code can run in. A flag left in place after release keeps an unused code path in the codebase.
-   **Changes can break the trunk together.** Two changes that each passed can fail once both merge. A [merge queue](https://specstory.com/learning/ci-cd/merge-queue) tests each change on top of the trunk and the changes ahead of it.

## How is trunk-based development different from Gitflow?

Gitflow is a branching model that Vincent Driessen described in [a 2010 post](https://nvie.com/posts/a-successful-git-branching-model/). It keeps two permanent branches, `master` for released code and `develop` for integration, plus feature, release, and hotfix branches. Both models can use release branches, but they differ on these points:

| Attribute | Trunk-based development | Gitflow |
| --- | --- | --- |
| Permanent branches | One trunk | `master` and `develop` |
| Feature work | Merges daily, behind a flag when unfinished | Stays on its branch until complete, then merges into `develop` |
| Releases | A tag or a release branch cut from the trunk | A release branch from `develop`, merged into both |
| Fixes | Made on the trunk, then copied to a release branch | A hotfix branch from `master`, merged into both |

Driessen later suggests a simpler workflow, e.g. GitHub flow, for [continuous delivery](https://specstory.com/learning/ci-cd/ci-vs-continuous-delivery-vs-deployment). In GitHub flow, each branch merges into the main branch through a pull request. He adds that Gitflow may still fit explicitly versioned software.

## FAQs

### Are feature branches allowed in trunk-based development?

Feature branches are allowed in trunk-based development when they are short, usually lasting hours rather than weeks. Each belongs to one developer or a pair and exists for code review and CI checks before it merges. The model avoids a branch that keeps a feature in isolation until the feature is complete.

### What is a feature flag?

A feature flag is a setting that the code checks at runtime to turn a code path on or off, often without a deploy. Flags let unfinished work merge daily without reaching customers. Each flag also adds a code path, so tests need to run with the flag both on and off.

### Does trunk-based development skip code review?

Trunk-based development does not skip code review. Teams usually review each change in a pull request on the day it is written. When review waits for days, branches stay open and authors batch their work into larger changes.

### How do release branches fit trunk-based development?

Release branches in trunk-based development are optional and are cut from the trunk shortly before a release. Teams that release from a tag skip them. In the model trunkbaseddevelopment.com describes, a fix is made on the trunk first and copied to the release branch, which never merges back.

---

Source: [What is trunk-based development? | vs. Gitflow | SpecStory](https://specstory.com/learning/ci-cd/trunk-based-development)