Trunk-based development with feature flags

In trunk-based development, developers collaborate on a single branch, the trunk, and merge small changes into it at least once a day. Branches, where they exist at all, live for hours rather than weeks. DORA’s research associates this way of working with higher software delivery performance: teams that keep three or fewer active branches and merge to trunk daily ship faster and more reliably than teams that batch work into long-lived branches.

Merging daily has an unavoidable consequence: unfinished features land on the trunk, and with continuous delivery they land in production. Feature flags are what make that safe. A flag keeps the unfinished code path hidden until the feature is ready, so the trunk stays releasable at every commit and the release becomes a separate, controlled decision.

This guide covers:

• Why teams move to trunk-based development and the two common ways to practice it.
• How feature flags hide unfinished work and decouple deployment from release.
• The workflow with Unleash, from creating a release flag to rolling the feature out.
• Practices that keep the trunk releasable, instant rollback, and retiring flags once features are fully rolled out.

Why teams move to trunk-based development

Integration pain scales with branch lifetime. A branch that lives for weeks drifts away from the code everyone else is changing, so it ends in a large, conflict-prone merge that is hard to review and hard to test. Teams compensate with integration phases and code freezes, which slow delivery further. Trunk-based development removes the problem at its source: changes integrate continuously, so no branch ever drifts far enough to make merging risky.

There are two common ways to practice it, and Unleash supports both:

Either way, the definition of done for a merge is the same: the trunk builds, passes its tests, and could be released. What trunk-based development deliberately gives up is the ability to hide unfinished work on a branch. That job moves to feature flags.

Hide unfinished work with feature flags

A feature rarely fits into a single day-sized merge, so on any given day the trunk contains features that are partly built. There are structural ways to keep them invisible: build the backend first and add the user interface as the final piece, which Martin Fowler calls a keystone interface, or swap implementations behind an abstraction using branch by abstraction.

A feature flag generalizes both techniques and adds something they can’t provide: runtime control. The unfinished code path merges and deploys with the flag off, and nobody can reach it. When the feature is complete, you release it by changing the flag, not by deploying code. GitHub’s feature flag write-up describes the payoff: disabling a change takes seconds, where a rollback deployment takes minutes.

This separation of deployment from release is what makes trunk-based development sustainable in production. Deployment becomes routine and low-stakes because unreleased code changes nothing for users. Release becomes deliberate and reversible because it happens at runtime, per environment and per audience, under your control in Unleash.

Implement the workflow with Unleash

To follow this workflow you need an Unleash instance and an application connected through one of the SDKs. See the quickstart for setup options.

1
import { startUnleash } from 'unleash-client';
2
3
const unleash = await startUnleash({
4
  url: 'https://YOUR-API-URL',
5
  appName: 'my-web-application',
6
  customHeaders: { Authorization: '<YOUR_API_TOKEN>' },
7
});
8
9
function processCheckout(cart, user) {
10
  if (unleash.isEnabled('new-checkout-flow', { userId: user.id })) {
11
    // Merged and deployed, but hidden in production until the flag is enabled
12
    return newCheckoutFlow(cart);
13
  }
14
  return currentCheckoutFlow(cart);
15
}

Keep the trunk releasable

The workflow only holds up if the trunk stays trustworthy. The practices DORA identifies for successful trunk-based development are the same ones that make flag-guarded merging safe:

• Fast, automated builds and tests on every merge. A build that takes minutes, not hours, is what makes merging several times a day practical.
• Small batches, reviewed quickly. A diff produced in a few hours is reviewed in minutes. Waiting a day for review reintroduces the long-lived branch through the back door.
• No code freezes. If a change isn’t ready to be seen, that’s a flag decision, not a reason to stop integrating.
• As few flags per feature as possible. One flag guarding one seam is easy to reason about and easy to remove. If one feature seems to need many flags, that’s usually a sign to split the feature. For managing flags across many teams, see best practices for feature flags at scale.

Roll back in seconds without reverting commits

When a released feature misbehaves, the flag is the retreat. Turning it off in the production environment returns every user to the previous code path in seconds, with no revert commit, no rollback deployment, and no impact on the other changes that shipped alongside it. The blast radius is exactly one feature.

You can automate the retreat as well. Safeguards monitor your metrics during a release plan and pause the rollout automatically when a threshold is crossed, and signals with actions let your monitoring or CI systems disable a flag without waiting for a human.

Retire flags when the rollout is done

A release flag has done its job once the feature has held at 100% and you no longer need the option to turn it off. Leaving it in place after that is unmanaged technical debt: every stale flag is a dead branch in the code and an if statement someone eventually misreads. Unleash surfaces cleanup candidates through the feature flag lifecycle, which highlights flags that have completed their rollout but haven’t been archived.

To clean up a release flag safely:

1. Confirm the feature is stable at 100% rollout and you no longer need the ability to turn it off quickly.
2. Remove the flag check from your code, keeping only the new code path, and deploy that change.
3. Archive the flag in Unleash. Archiving keeps the flag’s history, and you can revive it later if needed.

Make cleanup part of the feature’s definition of done, for example by creating the removal task at the moment a flag reaches 100% rollout. A trunk-based team creates flags constantly, so retiring them at the same rate is what keeps the codebase simple.

Frequently asked questions

Additional resources

• How to perform a gradual rollout
• Feature flag best practices
• Managing feature flags in code
• Best practices for feature flags at scale