Feature flag rollout
Staged rollout from internal users to 100% with a kill switch.
Shipping a feature to 100% of users in one deploy is a bet you do not need to make. This template draws the alternative every mature release process converges on: the feature ships dark behind a flag, the internal team uses it first with a fix-and-redeploy loop for bugs, then exposure ramps to 5% and 50% of users with a metrics health check at each stage. Any failed check hits the kill switch — flag off, behavior reverted in seconds, no rollback deploy — and routes back to a fix. Only after a healthy 100% rollout does the final step happen: the flag comes out of the code.
That last node is the one most teams skip and most codebases pay for. A rollout is not done until the conditional is gone.
When to use this template
- Release process documentation — codify the stages, the percentage steps, and who watches which metrics, so every launch follows the same ramp instead of an improvised one.
- Launch reviews — walk a specific feature through the diagram before enabling it: are the metrics defined, is the kill switch tested, who is on point at each stage?
- Engineering onboarding — teach the difference between deploying code and releasing a feature, with the kill switch as the concrete payoff.
How to adapt it
Tune the stages to your traffic and risk tolerance, then add your specifics:
- Adjust the percentage steps — high-traffic products often ramp 1% to 10% to 50%, while smaller ones may go straight from internal to 25%.
- Add a beta or opt-in cohort between the internal team and the first percentage stage for features that benefit from early feedback.
- Attach an experiment readout node at 50% if your flags double as A/B tests and the rollout decision depends on significance, not just health.
Visual edits regenerate clean Mermaid code, so the rollout playbook you shape in the editor pastes cleanly into your engineering handbook.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A[Feature behind flag] --> B[Enable for internal team]
B --> C{Bugs found?}
C -->|Yes| D[Fix + redeploy]
D --> B
C -->|No| E[Roll out to 5% of users]
E --> F{Metrics healthy?}
F -->|No| G[Kill switch: disable flag]
G --> D
F -->|Yes| H[Increase to 50%]
H --> I{Metrics still healthy?}
I -->|No| G
I -->|Yes| J[100% rollout]
J --> K[Remove flag from code]
Frequently asked questions
- What is a staged feature flag rollout?
- Instead of shipping a feature to everyone at once, you enable it for progressively larger audiences — internal team first, then 5% of users, then 50%, then 100% — checking bugs and metrics at each stage. This template draws that progression, including the kill-switch path that disables the flag the moment metrics degrade.
- Why does the diagram end with removing the flag from code?
- Because stale flags are technical debt: dead branches, untested code paths, and config that nobody remembers the meaning of. Treating flag removal as the final mandatory step of the rollout — not an optional cleanup someday — is the discipline that separates healthy flag usage from a codebase full of zombie conditionals.
- What metrics should gate each rollout stage?
- Watch error rates, latency, and crash rates for regressions, plus the product metric the feature is supposed to move — conversion, engagement, task completion. The diagram's two health checks (at 5% and 50%) are where you compare flagged users against the control group; if either check fails, the kill switch routes straight back to fix and redeploy.
- How is a kill switch different from a rollback?
- A rollback redeploys the previous build, which takes minutes and carries its own risk; a kill switch flips the flag off and reverts behavior in seconds with no deploy at all. That speed is the core argument for flags — and why this diagram routes both failed health checks to "disable flag" before any code change happens.