A canary deployment sends a new version to a small slice of traffic before the rest. The idea is that if something's wrong, it's wrong for 5% of users, not all of them. That containment only pays off if something actually looks at the canary and decides whether to proceed or pull back. A canary nobody is watching is just a slower way to find out the same thing broke everyone.
The two ways a canary stage ends
Every canary stage resolves one of two ways: it graduates (traffic advances to the next stage, eventually 100%) or it gets pulled back. Doing that decision manually means someone watching a dashboard for the duration of the canary window, ready to intervene; that works until the regression happens during a stage nobody happened to be staring at.
Automatic rollback replaces "someone watching" with "a guardrail evaluating." The canary stage carries a metric-backed policy: a threshold, an evaluation window, and an automatic abort if it breaches. That's no different in mechanism from any other staged rollout, but the canary framing makes the stakes concrete: this specific small slice of traffic is the blast radius you're deliberately limiting, and the guardrail is what keeps that limit real instead of aspirational.
Building the stages
A canary is really just the first stage of a staged rollout: 5%, then 25%, then 50%, then 100%, each scheduled to activate at a specific time, with strictly increasing target percentages and a final stage that must land at exactly 100.
POST /v1/environment-flag-configs/{environment_flag_config_id}/rollouts
{
"target_variation_id": "...",
"stages": [
{ "target_percentage": 5, "activate_at": "2026-08-26T14:00:00Z" },
{ "target_percentage": 25, "activate_at": "2026-08-26T14:10:00Z" },
{ "target_percentage": 50, "activate_at": "2026-08-26T14:25:00Z" },
{ "target_percentage": 100, "activate_at": "2026-08-26T14:40:00Z" }
]
}
The guardrail attaches to the rollout as a whole, not to an individual stage. It evaluates continuously as the rollout advances, so a regression that only shows up once traffic crosses from 5% to 25% (a common shape, since some failure modes only manifest under real concurrency) is still caught, not just the ones visible in the first few minutes.
What "small blast radius" actually requires
The 5% canary stage only limits blast radius if the metric being evaluated can actually see a problem at 5% of traffic. A metric aggregated across the entire fleet, diluted by the other 95% still on the old version, can hide a canary-stage regression that would be obvious if scoped correctly. Whether your metric pipeline can slice by rollout stage or deployment version is worth confirming before trusting a 5% canary to actually catch what it's supposed to catch. A canary stage with a metric that can't see it isn't containing risk, it's just delaying discovery by however long the next stage's dwell time is.