Feature Toggle
A feature toggle is a runtime switch that decouples deployment from release, enabling staged rollouts, kill switches, experiments, and permissioned access.
Definition
A feature toggle is a configuration decision evaluated at runtime to choose between code paths. Release toggles hide unfinished features, ops toggles act as kill switches, experiment toggles assign cohorts, and permission toggles restrict access. Each type has a different lifecycle and should be removed or made permanent deliberately.
Context and scope
Toggles are used to decouple deploy from release, test in production with a small audience, and disable a failing feature without a rollback. They are common in continuous delivery and progressive rollout systems.
Common misconceptions
- Toggles are free — every toggle adds branches, tests, and state combinations
- A toggle is a permanent configuration system — release toggles should be removed after rollout
- Flipping a toggle is always instant and safe — cached evaluation, background jobs, and in-flight requests may lag
Anti-patterns
- Leaving release toggles in the code for years
- Evaluating a toggle differently in different services for the same user
- Using a toggle to hide a broken feature instead of fixing or removing it
Related concepts
Authoritative source
Decouple deploy from release
A feature toggle lets code reach production without being visible to users. The deploy is a technical event; the release is a product decision. If the feature misbehaves, disabling the toggle is faster than rolling back a deployment, provided the old path is still present and tested.
if (flags.isEnabled('checkout_v2', { userId, tenantId })) {
return checkoutV2(cart);
}
return checkoutV1(cart);Know the toggle type
A release toggle hides unfinished work and should be removed after the rollout. An ops toggle is a long-lived kill switch for a dependency or feature. An experiment toggle assigns users to cohorts and needs analytics discipline. A permission toggle enforces access and must be evaluated consistently and securely. Mixing these purposes creates toggles that nobody dares remove.
Keep evaluation consistent
Evaluate the toggle once per request at a clear boundary and pass the decision down. Evaluating the same toggle in multiple services with different user context can produce inconsistent behavior. Cache flag values with a bounded staleness and a fallback default; if the flag service is unavailable, the system must still make a safe choice.
Clean up
Every release toggle is technical debt with a deadline. Track the owner, rollout state, and removal date. When the feature is fully rolled out, remove the old path and the toggle, and delete the flag configuration. A codebase with hundreds of stale toggles is a combinatorial testing problem.
When to use it
Use toggles when deployment and release need to be independent, when a kill switch is valuable, or when an experiment requires cohorts. The advantage is control and fast mitigation; the drawback is branching complexity and configuration drift. Compared to a redeploy, a toggle is faster but adds a runtime dependency and a cleanup obligation.