How-to
How to Move a Team to Trunk-Based Development in 7 Steps
- Long-lived feature branch
- Trunk-based development
- Loglune
On this page
- 01What trunk-based development means in practice
- 02Before you switch: inputs to check
- 03How to move a team to trunk-based development in 7 steps
- 04Git and GitHub setups for trunk-based development
- 05Editorial example (not a customer case): one feature over three days on the trunk
- 06Long-lived branches and GitFlow: when trunk-based development does not fit
- 07Troubleshooting trunk-based development
- 08FAQ
- 09Deciding whether trunk-based development fits your team
Trunk-based development is a source-control branching model in which every developer merges small changes into one shared branch, the trunk, at least once a day, and any other branch lives for hours instead of weeks. A team moves to trunk-based development in 7 steps: set a daily merge rule, cap branch lifetime, keep the build fast, review small changes quickly, hide unfinished work behind flags, release from the trunk, and remove flags when a rollout ends.
The steps assume a team that deploys a web service or API from one codebase. A team that ships installed software in several supported versions at once faces a different trade-off, covered in the section on long-lived branches below.
What trunk-based development means in practice
The site trunkbaseddevelopment.com defines trunk-based development as a source-control branching model where developers collaborate on code in a single branch called the trunk. The site accepts two working styles: committing directly to the trunk, or opening pull requests from short-lived feature branches, as long as each branch is short-lived and comes from one developer’s workstation.
The DORA capability page on trunk-based development contrasts feature-branch development with trunk-based development, where developers merge small batches of work into the trunk at least once a day. DORA calls trunk-based development a required practice for continuous integration, which DORA describes as trunk-based development combined with fast automated tests that run after each commit.
| Question | Long-lived feature branches | Trunk-based development |
|---|---|---|
| How long a branch lives | As long as the feature takes | No more than a few hours, per DORA |
| How often work reaches the shared branch | When the feature is complete | At least once a day |
| Where unfinished work waits | On the unmerged branch | In the trunk, switched off by a flag or hidden behind an abstraction |
| Release branches | A separate branch per release | Unnecessary when releasing several times a day, per DORA |
Before you switch: inputs to check
A move to trunk-based development changes daily habits, so check six inputs before the first rule changes.
- Test suite: a green build has to mean the trunk can ship, and DORA lists comprehensive automated tests among the practices.
- Build time: a build that takes longer than about ten minutes pushes developers back to batching work.
- Release cadence: how often production deploys today, and how often the team wants it to deploy.
- Review habit: DORA names heavyweight code review as an obstacle to trunk-based development.
- Flag system: unfinished work needs a switch before it can merge daily.
- Revert authority: every developer needs permission to revert a change that breaks the trunk.
How to move a team to trunk-based development in 7 steps
1. Name one trunk and set a daily merge rule
Pick the one branch everyone merges into and write down the rule that each developer merges at least once a day. The DORA practice list includes merging to the trunk at least once a day and running no code freezes or integration phases. A daily merge rule fails when a piece of work is too large to merge in a day, and step 5 handles that case.
2. Cap branch lifetime at hours and keep three or fewer active branches
A branch that lives longer than a day collects conflicts with everyone else’s work. The DORA page says branches in trunk-based development last no more than a few hours, and DORA lists three or fewer active branches in the code repository as a practice. The trunkbaseddevelopment.com site adds that short-lived feature branches are used for code review and CI runs, but release artifacts are not built from those branches.
3. Keep the build fast and fix a red trunk immediately or revert the change
When the trunk build fails, the DORA page says developers fix the problem immediately, or revert the change when the fix takes more than a few minutes. Martin Fowler’s article Continuous Integration (updated January 18, 2024) cites the ten-minute build from Extreme Programming as a reasonable target. A slow build pushes developers back to larger batches, which undoes the daily merge rule from step 1.
4. Review small changes synchronously
DORA names heavyweight code review as an obstacle and lists synchronous code review among the practices of trunk-based development. For example, a 50-line change reviewed within the hour keeps its branch inside the few-hour limit, while a 2,000-line change that waits two days for review breaks the limit. Pair programming and same-day review requests are two ways to keep review synchronous.
5. Hide unfinished work behind a release flag or branch by abstraction
Work that takes longer than a day still merges daily, switched off. The trunkbaseddevelopment.com site lists feature flags and branch by abstraction as the techniques for larger changes, together with the rule of not breaking the build. Pete Hodgson’s article Feature Toggles (October 9, 2017) describes release toggles as the way incomplete code paths ship to production as latent code, and calls release toggles transitionary. Fowler’s Continuous Integration article recommends a keystone interface where the new code can stay unreachable, and feature flags for the other cases.
In Loglune, each flag edit in the console or through the API is appended as a change event that records the customer, the actor, the time, the target flag, and the before and after values. A release flag that hides unfinished trunk code in Loglune therefore carries a dated history of every change to who could see the feature.
6. Release from the trunk and check what a customer received
With unfinished work switched off, any green trunk build can deploy, and the release happens when the flag rule changes. The DORA page notes that release branches are not needed when a team releases several times a day. Publishing a flag draft in Loglune creates an immutable version, and the Loglune SDK evaluates that version in your own process or at the edge and returns the value together with an evaluation record containing the version, the attribute key, and the returned value.
When a customer reports a problem after a flag change, pick the customer and the time T, or import the evaluation record from the report. Loglune rebuilds the flag state at T from the change history and delivers it in reproduction mode to a development, CI, or staging environment, and one delivery counts as one reproduction. Loglune reproduces the flag evaluation, and finding the defect in the application code remains debugging work.
7. Remove release flags when the rollout ends
A release flag that stays after the rollout keeps both code paths alive in the trunk. Hodgson describes a carrying cost for every toggle and says savvy teams treat their toggles as inventory and keep that inventory low. Add a removal task when the flag is created, and delete the flag check from the trunk once the rule serves one value to every customer. In Loglune, the edit that switches the flag on for everyone is itself a change event, which gives the removal task a dated starting point.
Git and GitHub setups for trunk-based development
In Git, trunk-based development uses the default branch as the trunk. A developer branches from the trunk, pushes small commits, and merges back the same day, either directly or through a pull request, and trunkbaseddevelopment.com accepts both styles as long as each branch is short-lived. On a hosted Git service such as GitHub, the same rules apply to pull requests: each pull request comes from a branch that lives for hours, passes the automated build before it merges, and is deleted after it merges. The hosting service does not change the model; branch lifetime and merge frequency define the model.
Editorial example (not a customer case): one feature over three days on the trunk
The table follows one feature, an invoice export, from the first merge to flag removal. Times and percentages are illustrative.
| When | Change merged to the trunk | Branch lifetime | Flag rule for invoice-export |
|---|---|---|---|
| Day 1, 10:00 a.m. | Data model and migration, not yet called | 3 hours | Flag created, off for every customer |
| Day 1, 3:00 p.m. | API endpoint behind the flag | 2 hours | Off for every customer |
| Day 2, 11:00 a.m. | User interface behind the flag | 4 hours | On for the internal team |
| Day 3, 9:00 a.m. | No code change | No branch | On for 10% of customers |
| Day 3, 4:00 p.m. | No code change | No branch | On for every customer |
| Day 10 | Flag check deleted from the code | 1 hour | Flag retired |
Every row in the example merges within hours, and the release itself happens on day 3 through flag edits, not through a merge.
Long-lived branches and GitFlow: when trunk-based development does not fit
Trunk-based development fits software that is delivered continuously and runs as one version. Vincent Driessen, who published the original git-flow branching model on January 5, 2010, added a note of reflection on March 5, 2020. In that note, Driessen suggests a much simpler workflow for teams that deliver web apps continuously, and says git-flow may still fit teams that build explicitly versioned software or support several versions in the wild. The trunkbaseddevelopment.com site recommends trunk-based development instead of GitFlow and other models with long-running branches.
Troubleshooting trunk-based development
- The trunk breaks several times a day: speed up the commit-stage tests, fix each broken build immediately, and revert the change when the fix takes more than a few minutes, as the DORA page describes.
- Branches still last several days: split the work into changes that merge the same day, and use branch by abstraction or a release flag for the part that is not ready.
- Unfinished features reach customers: default every new release flag to off and target the internal team first.
- Release flags pile up: attach a removal task to every release flag, because Hodgson describes each toggle as carrying cost.
- A customer reports a bug right after a flag change: read the evaluation record from the report, then rebuild the flag state at the reported time.
- Code reviews wait for days: move to synchronous review, which DORA lists among the practices of trunk-based development, because DORA names heavyweight code review as an obstacle.
FAQ
Is trunk-based development the same as continuous integration?
Trunk-based development is one part of continuous integration, not the whole practice. DORA describes continuous integration as trunk-based development combined with fast automated tests that run after each commit.
Do you still use pull requests in trunk-based development?
Pull requests work in trunk-based development when each pull request comes from a short-lived branch. The trunkbaseddevelopment.com site accepts both direct commits to the trunk and short-lived feature branches reviewed through pull requests.
Does trunk-based development work without feature flags?
Trunk-based development works without feature flags when every change is small enough to merge complete and visible. Larger changes need a way to stay switched off, and trunkbaseddevelopment.com lists feature flags and branch by abstraction for that case.
Is trunk-based development better than GitFlow?
Neither model wins for every team, and the deciding condition is how the software ships. Driessen’s 2020 note suggests a simpler workflow than git-flow for continuously delivered web apps, while explicitly versioned software with several supported versions may still fit git-flow.
Deciding whether trunk-based development fits your team
Trunk-based development fits a team that deploys one version of a service, has automated tests it trusts, and can keep builds near ten minutes. Start with the daily merge rule and the few-hour branch limit, add release flags for work that spans days, and record every flag change so a release that happens through a flag edit can be traced back to one customer and one moment. Keep a long-lived branch model when customers run several versions that the team must patch separately.
See the flag state a customer had after a trunk release
When unfinished work ships dark behind a flag, Loglune records every flag change as a change event. Pick a customer and a time T to rebuild the flag state that customer received and load it in development, CI, or staging. The Free plan includes 5 reproductions.