Let’s start with the core discipline before adding feature flags into the picture.

The basic idea

Trunk-Based Development (TBD) is a source-control practice where every developer integrates their changes into one shared branch — usually called main or trunk — extremely frequently, at least once a day, instead of working in isolation on a long-lived feature branch for weeks at a time. The branch itself is kept in a permanently releasable state, meaning it could, in theory, be deployed to production at almost any moment.

Frequent integration solves one problem but immediately creates another.

If every developer merges into main multiple times a day, and main is deployed frequently, then a feature that takes three weeks to build has to live inside that shared branch the entire time — half-built, not ready for real users. Without a way to hide unfinished work, teams are forced back into long-lived branches just to avoid exposing incomplete features, which quietly undoes the entire benefit of trunk-based development in the first place.

That “something” is a feature flag — and it’s the mechanism that makes trunk-based development actually workable at real organizational scale, rather than just a nice idea that falls apart once more than a handful of developers share one branch.

The single idea that unlocks everything else in this article.

The basic idea

A feature flag (also called a feature toggle) is a conditional check in running code — an “if this flag is on, do the new thing; otherwise, do the old thing” branch — that decides, at runtime, whether a piece of functionality is active. Critically, the flag’s state can be changed without redeploying any code at all, usually through a small configuration dashboard.

graph LR
    A[Developer writes new feature behind a flag] --> B[Merged into main same day]
    B --> C[CI runs tests automatically]
    C --> D[main deployed to production]
    D --> E{Flag On?}
    E -->|No| F[Users see old behavior]
    E -->|Yes for target group| G[Users see new feature]
        

Notice the shape of this: the branch merge happens quickly and constantly (trunk-based development’s job), while the actual exposure to users happens separately and gradually, controlled entirely by the flag (feature flags’ job). Each mechanism solves a different half of the same underlying problem.

Not every flag serves the same purpose — recognizing the type helps decide how long it should live.

Trunk-based development’s core promise — that main is always deployable — has to be mechanically enforced, not just hoped for.

GitHub Actions runs automatically on every push and every pull request targeting main, executing the build, the automated test suite, and any linting or security checks before a change is allowed anywhere near the shared branch. Combined with a branch protection rule or ruleset requiring those checks to pass — and typically requiring at least one reviewer’s approval — this is what turns “we try to keep main releasable” from a team promise into something the platform actually guarantees.

Even once a flag is turned on, it rarely goes to 100% of users at once.

GitHub Environments let a deployment pipeline define distinct stages — such as staging, then a canary slice of production, then the rest of production — each with its own required approvals and protection rules. A team commonly combines this with a feature flag that starts targeting a tiny internal group, widens to a small percentage of real users, and only reaches everyone once the earlier rings show no problems.

graph TD
    A[Flag: Internal team only] --> B[Flag: 5 percent of users]
    B --> C[Flag: 25 percent of users]
    C --> D[Flag: 100 percent of users]
    D --> E[Flag deleted, code becomes permanent]
        

Perhaps the most underrated benefit of feature flags has nothing to do with gradual rollout at all.

If a newly released feature starts causing errors or performance problems in production, a team using feature flags can simply turn the flag off — reverting user-visible behavior in seconds, through a configuration change, with zero code deploy and zero risk of introducing a new bug during a rushed rollback. Compare that to a team without flags, who would need to revert a commit, wait for CI, and redeploy — a process that takes meaningfully longer during an active incident.

A common beginner question: is a feature flag just a variable in the code?

Not quite — the whole point is that the flag’s current value is stored outside the deployed code, typically in a dedicated feature-flag management service or a lightweight configuration store the application checks at runtime. The application code only contains the conditional logic (“if flag X is on, do Y”); the actual on/off/percentage decision lives in a system a non-engineer, like a product manager, can safely adjust without ever touching a Git repository.

You may likeWhat Is the Reflog?→

A flag that no one is watching is just an untracked risk sitting in production.

Mature teams tag their monitoring and error-tracking data with which flags were active for a given request, so if error rates spike, they can immediately see whether the spike correlates with a specific flag being turned on for a specific group — turning “something broke, and we don’t know why” into “flag X caused this, and we can turn it off right now.”

Not quite — short-lived branches for individual pull requests are still normal and encouraged. What’s avoided is a branch that stays open and diverges from main for weeks at a time.

Yes — that’s the entire point. The flag’s value lives outside the deployed code, in a configuration store, so flipping it doesn’t require a new build or deployment.

GitHub Actions doesn’t manage flag state itself — its role is enforcing that whatever gets merged into main, flagged or not, passes tests and review, which is what makes it safe to merge unfinished work behind a flag in the first place.

The flag simply stays off indefinitely, and the dormant code sits harmlessly in the codebase until either the feature is resumed or the flag and its code are deliberately removed.

No — even a small team benefits from smaller, safer merges and instant rollback, though the scaling benefits (avoiding painful long-branch merges, ring-based rollout across many users) become most visible as the team and user base grow.

Trunk-Based Development keeps one shared branch always releasable by insisting on small, frequent merges instead of long-lived, drifting feature branches. On its own, that discipline creates a problem: unfinished work has nowhere to hide. Feature flags solve exactly that problem, separating the moment code is deployed from the moment it’s actually released to users — and in doing so, they let a team merge constantly, roll out gradually, and roll back instantly, all without a single extra deploy.