Release templates and guarded releases

Releasing every flag the same careful way shouldn’t mean typing the same rules into every flag and environment. A release template is that rollout written once per project. Applied to a flag in an environment, it becomes the flag’s release plan, which you move through one step, a milestone, at a time, by hand or on a timer. A plan can also be guarded: it watches your metrics while each milestone is live, and pauses or steps back when the new variant does worse.

Templates

Create templates on the project’s Templates page. Two presets are there to start from:

• Gradual: 10%, 25%, 50% and everyone, a day apart.
• Staff first: the staff segment first (if the project has one), then 10%, 50% and everyone, a day apart.

A milestone is the targeting it puts in force, rules and a default, written without knowing any flag’s variants: it serves the release (the new variant), the fallback (the old one), or a percentage of the release with the rest on the fallback. Its rules can use the project’s segments, such as “staff gets the release”. A milestone can also say how long until the next one starts on its own (90m, 24h, 7d); without that, the next waits for someone to start it.

Templates that advance on their own need a plan with scheduled changes (Team or Business). Templates you advance by hand work on every plan.

Release a flag

Open the flag, pick the environment and choose Use a template on its Release tab. For a boolean flag the release is true and the fallback false; for other flags you pick the two variants. The plan takes its own copy of the template, so editing the template later never changes a release under way.

If the flag is on, the first milestone starts straight away; if it’s off, the plan waits for you to start one. From then on the Release tab shows each milestone, which is live and since when, and the next start with its time.

• Start any milestone, forward or back. Go back is the way out when something looks wrong.
• Pause stops the timer; Resume starts it again from now.
• Remove takes the plan off and leaves the flag’s targeting as it is.

Every milestone start is an ordinary change to the flag, so the environment’s rules apply to it: a required comment, approvals (each timed start waits for reviewers ahead of its time), history, restoring and webhooks. If someone edits the flag’s rules or default by hand, or turns the flag off, the plan pauses so it doesn’t overwrite their change. Individual targets, prerequisites and turning the flag on don’t pause it.

A flag with a release plan in an environment can’t run an experiment there, since both would write the same rules.

Guarded releases

On Team and Business, a plan can watch some of the project’s metrics while each percentage milestone is live, comparing users on the release with users still on the fallback, the way an experiment does. When the release does worse on a metric, with a chance at or above the guard’s threshold (95% by default), the plan stops the release by itself:

• Pause: the plan stops where it is, and you decide what next.
• Roll back: the plan goes back one milestone and pauses. At the first milestone, it serves the fallback to everyone the rollout covered.

You choose the policy per metric, up to ten metrics, and a minimum number of users on each side before anything is judged (500 by default), so a small early sample doesn’t trip it. The plan records what it saw and what it did, and emails the person who started the release and the environment’s admins. A rollback doesn’t wait for approval: the approved release stands for it, and a guard that waited for reviewers would protect nothing.

What a guard needs:

• The environment’s experiment key, and SDKs set up for experiments: they report for a guarded release exactly as for an experiment, and track the events its metrics count.
• Milestones it can measure: a percentage of the release, split by user key. Milestones that serve the release to everyone, or to a segment, have nothing to compare and aren’t watched.

Metrics never move a plan forward: a healthy milestone still waits for its timer or for you. After a pause, resuming starts a fresh comparison, so the harm already measured doesn’t trip it again. A guard keeps working when the organisation’s account is read-only after a failed payment, as kill switches do.

From the API

curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' "$API/projects/acme/release-templates/gradual" \
  -d '{"milestones":[{"name":"10%","default":{"rollout":{"release":10000}},"advance_after":"1d"},{"name":"everyone","default":{"role":"release"}}]}'
curl -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' "$API/projects/acme/flags/new-checkout/environments/production/release-plan" \
  -d '{"template":"gradual"}'
curl -X POST -H "Authorization: Bearer $TOKEN" "$API/projects/acme/flags/new-checkout/environments/production/release-plan/milestones/2/start"
curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' "$API/projects/acme/flags/new-checkout/environments/production/release-plan/guard" \
  -d '{"guardrails":[{"metric":"page-errors","policy":"rollback"},{"metric":"checkout-completed","policy":"pause"}]}'

Percentages in the API are in thousandths of a percent: 10000 is 10%. Templates are also a Terraform resource, featflags_release_template, and an AI assistant can start a milestone for you.