Schedule a change or a staged rollout
Plan a flag change for a set time, or raise a rollout in stages, and follow each step as it runs.
- Time
- About 8 min
- Who can do it
- Anyone with releases.create who may also make the change. Release managers and Admins can review.
- Where
- Flags > your flag > Releases, then Releases
- You finish with
- A release that applies its changes on time
What and why#
What it is#
A release is a plan to change one flag in one environment. Instead of switching something yourself at 09:00, you write the change down, give a reason and a time, and the server applies it. A release is made of steps, and each step sets the flag on or off, a rollout percentage, or both.
When to use it#
- A launch at a set time, so nobody has to be at a keyboard.
- A rollout that widens by itself, such as 5, 25, 50 and 100 percent two hours apart.
- A change that must be reviewed first. In an environment that requires approval, a release is the only way to turn a flag on or off or move its percentage.
How it works#
You propose the release. If it needs review it waits as Needs approval, otherwise it is Scheduled. A timer on the server checks for due steps every 15 seconds and applies them in order. The kind follows from the steps: one step now is a change, one step later is a scheduled change, and several steps are a rollout.
Before you start#
- The
releases.createpermission, and the permission for each kind of change in it:flags.toggleto turn the flag on or off androllouts.updatefor a percentage. See Give people the right access. - A flag that is not archived, with the environment you want to change. An archived flag refuses new releases.
- Review. A release always waits for a Release manager or an Admin when the environment requires approval, and also whenever the proposer cannot review releases, such as a Developer. See Put production behind review.
Walk through it#
Open the flag's Releases tab
Choose the environment and the kind
Fill in the top of the dialog. The Environment list shows only environments the flag is set up in.
Fields in the Propose a release dialog Field Description Environment* Where the change applies. Kind One change, now or later (the default) or Progressive rollout. Reviewer Shown only when the release needs approval. Optional: it asks one Release manager or Admin by name, and every reviewer can still decide. You cannot name yourself. Reason* Up to 200 characters. Reviewers and the audit log show it. Describe the change
For One change, now or later:
One change Field Description Flag Leave as it is (default), Turn on or Turn off. Rollout percentage A whole number from 0 to 100. Leave it empty to keep the current one. At least one of Flag and Rollout percentage must change, or the planner refuses with a message asking what to change. For Progressive rollout:
Progressive rollout Field Description Stages Percentages separated by commas or spaces, such as 5, 25, 50, 100(the default). At least two, at most 20, whole numbers from 0 to 100, each larger than the one before.Minutes between stages At least 1. The gap is the same between every stage. Up to 20,160 (14 days). Turn the flag on with the first stage On by default. The first stage sets the percentage first and then switches the flag on, so it never serves the old split. The Propose a release dialog set up as a progressive rollout. Switch Kind back to One change, now or later to see the Flag and Rollout percentage fields instead. Choose when it starts
Leave Start as soon as allowed on to begin straight away (after approval, if needed). Switch it off to set a Start time. The picker shows your own time zone, which is saved with the release as Planned in; times are stored in UTC. A time in the past means as soon as possible, and a start more than a year ahead is refused.
Send it, then follow it
Choose Propose release. On the Releases page, use the filters Open, Needs approval, Rejected and All. You can also filter by who proposed it, project, flag and date created. Choose Show details on a card to see each stage, its due time and what happened.
A scheduled rollout after its first stage ran. Green marks an applied stage, the blue bar is the next one. You should see. The release appears with a row of stages. It reads Scheduled and shows when the next stage runs (for example1 of 4 stages applied · next in 2 hours), or Needs approval when a review comes first.Release statuses Status Description Needs approval Waiting for a reviewer. Scheduled Approved or not needing review, and waiting for its time. Applying A step is being applied now. Completed Every step ran. Failed A step was refused or kept failing. The remaining steps are skipped. Rejected / Cancelled A reviewer said no, or the person who proposed it withdrew it, or nobody reviewed it in time. Withdraw it if plans change
While a release is waiting or scheduled, the person who proposed it can choose Cancel and confirm. Steps that have not run are cancelled. Steps already applied stay applied, and the release cannot be restarted. Reviewers cannot cancel someone else's release: they reject it instead.
The cancel confirmation. The secondary button is Keep release, which closes the dialog and changes nothing; Cancel release is the one that acts. While it runs, both buttons and the close button are locked.
Limits to know
How a step runs#
- The server checks for due steps every 15 seconds, so a step runs shortly after its time. An approved step whose time has already passed runs straight away.
- Each step sets an explicit state, so running one twice does no harm.
- A step that fails for a temporary reason is tried up to three times, with a wait that starts at 15 seconds and doubles up to five minutes.
- A refusal is not retried. It marks the step Failed and skips the rest. Refusals include an active kill switch, an archived flag, or the person the release runs as having lost the permission or left the organization.
- The release runs with the authority of the reviewer when it needed approval, otherwise of the person who proposed it.
- A failed release notifies the people set up to be told, and each applied, failed or completed step is recorded in the audit log.
Do it with the API#
Releases are Dashboard endpoints, so they authenticate with your signed-in session cookie (auth_session), not an API key.
Schedule one change
Needs releases.create and the permission for each change in the steps. steps takes up to 20 entries in time order, each with runAt and changes of enabled and/or rolloutPercentage. For an equally spaced rollout send rollout with startAt, percentages, intervalMinutes and enableFirst instead.
curl -s -X POST "https://flags.example.com/api/releases" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{
"flagId": "'"$FLAG_ID"'",
"environment": "production",
"title": "Launch new dashboard",
"timezone": "Africa/Lagos",
"steps": [
{ "runAt": "2026-10-05T08:00:00Z", "changes": { "enabled": true, "rolloutPercentage": 10 } },
{ "runAt": "2026-10-06T08:00:00Z", "changes": { "rolloutPercentage": 100 } }
]
}'{
"status": "success",
"message": "Release proposed",
"data": {
"id": "6650e3b4c5d6e7f8a9b0c1d2",
"flagKey": "new-dashboard",
"environment": "production",
"title": "Launch new dashboard",
"kind": "rollout",
"status": "pending_approval",
"requiresApproval": true,
"nextRunAt": "2026-10-05T08:00:00.000Z",
"timezone": "Africa/Lagos",
"steps": [
{ "index": 0, "runAt": "2026-10-05T08:00:00.000Z", "changes": { "enabled": true, "rolloutPercentage": 10 }, "status": "pending", "attempts": 0 },
{ "index": 1, "runAt": "2026-10-06T08:00:00.000Z", "changes": { "rolloutPercentage": 100 }, "status": "pending", "attempts": 0 }
],
"mine": true
}
}Follow it and withdraw it
The list needs releases.read and returns items, pagination and counts of releases waiting for approval and scheduled. status can be open or a single status such as failed. See the Releases API.
# Open releases for one flag
curl -s "https://flags.example.com/api/releases?status=open&flagId=$FLAG_ID" \
-b "auth_session=$SESSION"
# Cancel one (only its proposer can)
curl -s -X POST "https://flags.example.com/api/releases/$RELEASE_ID/cancel" \
-b "auth_session=$SESSION"What to check#
- The release card shows the stages and the next run time in your time zone.
- After a step runs, the flag's History & rollback tab shows a new version and Activity shows the change.
- A
Failedrelease opens with the failed step and its error visible. Fix the cause and propose a new release.
If something goes wrong#
Choose what to change (turn the flag on or off, or set a rollout percentage)
Why: A single change with Flag left as Leave as it is and no rollout percentage has nothing to apply.
Fix: Pick Turn on or Turn off, or enter a percentage.
Each stage must be larger than the one before
Why: The stages do not climb, or there are fewer than two.
Fix: Write 5, 25, 50, 100 and not 5, 50, 25.
Schedule no more than a year ahead
Why: A start time or step time is further away than 365 days.
Fix: Choose a nearer time, or propose it again closer to the date.
Ask someone else to review your release
Why: You named yourself as the reviewer, and self-approval is off.
Fix: Pick another Release manager or Admin, or leave Reviewer empty.
Cancelled with a note that it was not reviewed within 72 hours
Why: Requests nobody reviews expire after 72 hours.
Fix: Propose it again and tell your reviewer.
A release is Failed and the rest of its steps were skipped
Why: A step was refused: the kill switch is on in the environment, the flag was archived, or the reviewer can no longer change that environment.
Fix: Read the error under the failed stage, fix the cause and propose a new release.
Nothing happens at the planned time
Why: The release is still Needs approval, or the server runs without its scheduler (SCHEDULER_ENABLED=false on every instance).
Fix: Check the status on the Releases page. For the scheduler see Run FlagSwift in production.
Good to know#
Name a reviewer, but expect anyone to answer