Trunk-Based Development

flowchart LR
  M0["main"]
  M1["main"]
  M2["main"]
  M3["main"]
  M4["main"]
  PR1["PR #1<br/>2h"]
  PR2["PR #2<br/>4h"]
  PR3["PR #3<br/>1h"]
  PR4["PR #4<br/>3h"]

  M0 --> PR1 --> M1
  M1 --> PR2 --> M2
  M2 --> PR3 --> M3
  M3 --> PR4 --> M4

  style M0 fill:#E6F8F2,stroke:#1CB893,color:#1A1D24
  style M1 fill:#E6F8F2,stroke:#1CB893,color:#1A1D24
  style M2 fill:#E6F8F2,stroke:#1CB893,color:#1A1D24
  style M3 fill:#E6F8F2,stroke:#1CB893,color:#1A1D24
  style M4 fill:#E6F8F2,stroke:#1CB893,color:#1A1D24

The workflow itself is unremarkable. An engineer pulls main, branches off for a few hours, opens a PR, gets review, runs CI, merges. The next morning they pull main again. Most engineers who do this for the first time find the workflow itself simpler than what they were doing before.

What makes it work in practice is a small set of practices that have to be in place. Skip any of them and trunk-based development quietly degrades back into feature branching with a different name.

Short-lived branches

Branches that live longer than one day are a smell. The DORA research draws the line at 24 hours, and high-performing teams in the survey are well under that. Anything bigger gets split: into stacked PRs (link a chain of dependent branches together), into a refactor PR followed by a feature PR, or into shippable behind-a-flag steps.

Feature flags

For any change bigger than a few hours of work, the code lands behind a flag. The flag is off in production, on for the engineers shipping the feature, and gradually rolled out to users when the work is done. Without flags, trunk-based development falls back into long-lived branches because engineers hold their work locally until everything is done. With flags, the branch lifetime is decoupled from the feature lifetime, which is the entire point.

Branch by abstraction

Feature flags do not work for refactors. You cannot put a flag on "the new database client". The pattern is branch by abstraction: introduce an interface, run the old and new implementations side by side behind it, switch traffic over, then delete the old code. Each step is a small PR. None of them require a long-lived branch.

Fast CI

If CI takes 45 minutes, nobody is going to merge four times a day. The CI pipeline has to fit inside the cycle of "make a change, push, wait, merge." Around 10 to 15 minutes is the upper bound where most teams stay productive. Beyond that, parallelization, selective testing (run only the tests affected by the change), and two-step CI are the levers.

A green main, enforced

This is where teams trip. With everyone merging into one branch all day, two PRs that each pass CI in isolation can break main when they land together. A function gets renamed in PR #1 while PR #2 adds a caller. Both pass their own CI. Main is red the moment the second one merges. The fix is a merge queue that tests each PR against the future state of main before it merges. Without one, trunk-based development at any reasonable team size becomes a permanent firefighting exercise.

See the Mergify merge queue docs for what the configuration looks like in practice.

A simplified view of one engineer's day on a trunk-based team:

Two PRs in one day, both small, both reviewable in under fifteen minutes, both merged behind a flag that protects users from the half-finished feature. Tomorrow, the engineer pulls main and continues. There is never a "merge week." Integration is just what mornings look like.

When a team tries trunk-based development and it does not stick, it almost always comes down to two things.

"Our CI takes too long"

If CI takes 45 minutes, nobody merges four times a day. The fix is to make CI faster, and the levers are well known. Selective testing (only run tests affected by the change) typically cuts CI time by 50 to 80 percent on a monorepo. Two-step CI runs lightweight checks on every PR and the full suite only inside the merge queue. Parallel queues let a frontend PR merge without waiting on a backend one. None of these require rewriting CI from scratch.

"We can't ship half-finished features"

This is what feature flags are for. If the product team is uncomfortable with code landing in main before the feature is done, the answer is dark launches: the code is in main, the flag is off, no user sees it. When the feature is ready, the flag turns on for 1 percent of users, then 10, then everyone. The branch never has to live for a month, because the flag does the work the branch was doing.

Both of these are infrastructure problems, not workflow problems. Asking engineers to "be more disciplined about merging" without fixing them does not work.