Guide

Trunk-based development with feature flags

How teams merge to main every day without shipping half-finished features: the workflow, where feature flags come in, and the habits that keep it from turning into a mess of stale flags.

Trunk-based development is a way of working in which everyone merges small changes into one shared branch (the trunk, usually main) at least once a day, and the trunk is always releasable. Feature flags make that possible for work that takes longer than a day: the code ships, switched off, until it is ready.

Why teams move to trunk-based development

Long-lived feature branches look safe, but the cost arrives at merge time: conflicts, surprise interactions with other branches, and big-bang releases that are hard to review and harder to roll back. Integrating daily keeps every merge small. The DORA research programme lists trunk-based development among the capabilities that predict higher software delivery performance.

The problem it creates

If everyone merges to main daily and main is always releasable, what happens to a feature that takes three weeks? Its code is in main from day one, and it will be deployed many times before it is finished. Something has to keep users from seeing it. That something is a feature flag.

Separate deploy from release

The key idea: deploying puts code on servers; releasing lets users use it. With a flag around the new code, the two happen at different times and are decided by different people:

DeployRelease
What happensNew code runs in production, switched offThe flag turns on for some or all users
How oftenMany times a dayWhen the feature is ready
Decided byThe pipelineThe team, product or on-call
UndoRoll back the buildTurn the flag off, in seconds

The workflow, step by step

  1. Create the flag first, off in every environment except your own development one. Name it for the feature: new-checkout.
  2. Merge behind the flag, daily. Every pull request is small and keeps main green. The old path stays the default.
  3. Turn it on where you need it: for yourself, then your team, in staging, using targeting rules rather than code changes.
  4. Release gradually. Internal users, then a percentage rollout of 5%, 25%, 100%, watching errors and metrics at each step. Turning it off is always one click.
  5. Remove the flag. Once the feature is at 100% and stable, delete the flag and the old code path in one small pull request. This is the step teams skip; see cleaning up feature flags.

What the code looks like

Keep the branch at the edge: decide once, near the entry point, and keep both implementations separate so the old one is easy to delete later.

// One decision at the edge. Both paths stay whole, so removing the flag is a small diff.
const useNewCheckout = await flags.getBooleanValue('new-checkout', false, { targetingKey: user.id });

const checkout = useNewCheckout ? newCheckout : legacyCheckout;
return checkout.start(cart, user);

Avoid scattering the same flag check through dozens of files. If a feature needs checks in many places, pass the decision down, or put the new behaviour behind an interface with two implementations.

Other ways to hide unfinished work

Flags are not the only tool, and small changes often don't need one:

  • Dark launching: build the backend first and don't expose it until the UI exists.
  • Branch by abstraction: introduce an interface, move callers to it, build the new implementation behind it, then switch.
  • Keystone interface: build everything except the one link or button that makes it reachable, and add that last.

Use a flag when you want to control who sees the change and when, or to be able to turn it off instantly.

Pitfalls and how to avoid them

  • Flag debt. Every release flag is temporary. Give it an owner, review flags regularly and delete them once released.
  • Untested combinations. Test both paths while the flag exists. Avoid flags that depend on other flags.
  • Slow flag checks. With flags on many code paths, evaluate them locally in your process, so a check costs microseconds and no network call.
  • Unreviewed releases. Turning a flag on in production is a release. Require approval for production and keep an audit log of who turned what on and why.
  • Different answers in different services. If your API and your frontend evaluate the same flag, they must agree for the same user, or users see half a feature.

Frequently asked questions

What is trunk-based development?
Trunk-based development is a branching model in which developers merge small changes into one shared branch, the trunk or main, at least daily. Branches are short-lived, usually hours, and the trunk is always kept releasable.
Do I need feature flags for trunk-based development?
For any feature that takes longer than a day, yes in practice. Flags let unfinished code be merged and deployed while staying switched off, so the trunk stays releasable without long-lived branches.
Is trunk-based development the same as continuous deployment?
No. Trunk-based development is about how code is integrated. Continuous deployment is about shipping every change that passes the pipeline. Trunk-based development makes continuous deployment practical, but you can practise it with scheduled releases too.
How do pull requests fit into trunk-based development?
Short-lived branches with small pull requests are compatible with trunk-based development, as long as each branch is merged within a day or two and reviews are fast. The aim is small, frequent integration, not the absence of review.

Merge daily, release when ready

Railflag gives every release flag gradual rollouts, a one-click off switch, reviewed Production changes and a Stale view that tells you when to delete it.

Start for free