Skip to content
FlagSwiftDocs

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.create permission, and the permission for each kind of change in it: flags.toggle to turn the flag on or off and rollouts.update for 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#

  1. Open the flag's Releases tab

    Open Flags, choose the flag and open the Releases tab. Choose Propose release. The Releases page lists releases for every flag but does not create them.

  2. 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
    FieldDescription
    Environment*Where the change applies.
    KindOne change, now or later (the default) or Progressive rollout.
    ReviewerShown 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.
  3. Describe the change

    For One change, now or later:

    One change
    FieldDescription
    FlagLeave as it is (default), Turn on or Turn off.
    Rollout percentageA 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
    FieldDescription
    StagesPercentages 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 stagesAt least 1. The gap is the same between every stage. Up to 20,160 (14 days).
    Turn the flag on with the first stageOn 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.
  4. 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.

  5. 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 example 1 of 4 stages applied · next in 2 hours), or Needs approval when a review comes first.
    Release statuses
    StatusDescription
    Needs approvalWaiting for a reviewer.
    ScheduledApproved or not needing review, and waiting for its time.
    ApplyingA step is being applied now.
    CompletedEvery step ran.
    FailedA step was refused or kept failing. The remaining steps are skipped.
    Rejected / CancelledA reviewer said no, or the person who proposed it withdrew it, or nobody reviewed it in time.
  6. 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

A release has at most 20 steps and cannot start more than a year ahead. Percentages are whole numbers from 0 to 100, and a progressive rollout needs at least two stages. Steps change only the on or off state and the percentage: they cannot carry targeting, rules or segments, and there is no promotion between environments and no automatic rollback.

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.

Request
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 } }
    ]
  }'
201 Created (trimmed)
{
  "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.

Request
# 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 Failed release 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

Naming a reviewer sends them a request, but any Release manager or Admin can approve or reject. Leave a clear reason so whoever opens it first understands the change.
Why is the Reviewer list shorter than my team?
The list only offers members whose role can review releases, and never yourself. It also appears only when the release needs approval.
Can two releases for the same flag overlap?
Yes. Each runs on its own and each step sets an explicit value, so the later step wins. Cancel the one you no longer want.
What if I change the flag by hand before a step runs?
The step still applies its value at its time and overwrites your change. Cancel the release first if you no longer want it.
Do scheduled changes follow my time zone?
You choose the start in your own time zone and it is stored in UTC, so daylight saving never moves it. The card shows times in the viewer's time zone.
Can I schedule a rollback?
Not as such. A step can set the percentage back down or turn the flag off. A rollback to a saved version is immediate. See Review history, compare versions and roll back.