Release controls

Release controls govern when and how a flag’s per-environment change reaches the live ruleset. A change can apply immediately, wait for a second reviewer, wait for a scheduled time, or step a rollout up over an interval. They build on the same env-settings edit and change history a manual edit uses, so a deferred change lands exactly as if you had saved it by hand.

Immediate edits keep going through the env-settings save (the Targeting tab, or PUT .../flags/{key}). Everything below is for changes you want to hold back.

Environment promotion

Promotion copies one environment’s targeting settings for a flag into another environment, such as staging to production. The UI shows the source and target diff before writing the target; over the API call:

POST /api/v1/workspaces/{ws}/projects/{p}/environments/{e}/flags/{key}/promote
{"target": "prod"}

{e} is the source environment slug and target is the target environment slug. The target must exist and must differ from the source. Promotion writes the target’s enabled, off_variation, targets, rules, and fallthrough settings, then records audit and flag-change history and bumps the SDK ruleset.

Deferred changes

A deferred change carries the proposed env settings and a mode. Create one from the Targeting tab with Defer this change, or over the API:

POST /api/v1/workspaces/{ws}/projects/{p}/environments/{e}/flags/{key}/changes
GET  /api/v1/workspaces/{ws}/projects/{p}/environments/{e}/flags/{key}/changes

Field	Meaning
`mode`	`approval` (wait for a reviewer) or `scheduled` (wait for `execute_at`).
`settings`	The proposed env settings: `enabled`, `off_variation`, `targets`, `rules`, `fallthrough`. Validated up front.
`execute_at`	For a scheduled change, an RFC 3339 time in the future.
`comment`	An optional note shown in the queue and recorded in history.

The proposed settings are validated when the change is created, so a change cannot be queued in a shape that would only fail when applied.

Approvals (four eyes)

An approval change starts pending and applies nothing until a reviewer other than its author approves it. The flag’s Release tab lists the pending changes for that environment with approve, reject, and cancel actions.

POST   /api/v1/workspaces/{ws}/projects/{p}/flag-changes/{id}/approve
POST   /api/v1/workspaces/{ws}/projects/{p}/flag-changes/{id}/reject
DELETE /api/v1/workspaces/{ws}/projects/{p}/flag-changes/{id}
GET    /api/v1/workspaces/{ws}/projects/{p}/flag-changes

Approving applies the proposed settings, records the reviewer, and marks the change applied. The author cannot approve their own change. Rejecting records the reviewer and an optional reason and applies nothing. Either the author or anyone who can edit flags may cancel a change before it lands.

Scheduled changes

A scheduled change starts scheduled and is applied by the worker once its execute_at has passed (within one worker tick). Until then it can be cancelled. A scheduled apply lands the proposed settings and bumps the SDK ruleset version just like an immediate edit.

Progressive rollouts

A progressive rollout steps a treatment variation up to 100% over an interval, serving the remainder to a baseline variation. Start and control it from the flag’s Release tab or the API:

POST /api/v1/workspaces/{ws}/projects/{p}/environments/{e}/flags/{key}/ramp
GET  .../ramp
POST .../ramp/pause
POST .../ramp/resume
POST .../ramp/abort

Field	Meaning
`variation`	The treatment arm being ramped up.
`baseline`	The control arm serving the remaining share at each step.
`steps`	Ascending percentages ending at 100, for example `[1, 5, 25, 50, 100]`.
`interval`	The wait between steps, for example `1h`.
`guarded`	Link the ramp to the flag’s guarded release (see below).

The worker applies the first step on its next tick and each later step once the interval elapses, rewriting only the flag’s fallthrough so existing rules and targets are preserved. The final 100% step serves the treatment outright and completes the ramp. Pausing stops stepping where it is; resuming continues from the current step; aborting stops the ramp at its current rollout. Only one ramp runs per flag and environment at a time.

Guarded ramps

Set guarded to link a ramp to the flag’s guarded release. Starting the ramp arms the guarded release, capturing the pre-ramp fallthrough as the safe state, so the worker auto-rolls-back the rollout on a guardrail or SLO breach. When that rollback fires, the ramp aborts rather than fighting the revert. A guarded ramp needs a guarded release configured with a guardrail metric or a linked SLO, and a current fallthrough to revert to.

Permissions

Permission	Allows
`flags:read`	View pending changes, the ramp status, and change history.
`flags:write`	Promote settings, request approval, schedule a change, cancel one, and start, pause, resume, or abort a ramp.
`flags:manage`	Approve or reject a change (a reviewer who is not its author).