Skip to content
FlagSwiftDocs

Roll out a feature to a few, then everyone

Turn a flag on for a small share of people, watch what happens and widen it in steps, without redeploying anything.

Time
About 10 min
Who can do it
Release manager or Admin in production. Developer, Release manager or Admin in other environments.
Where
Flags > your flag > Targeting & rollout, then Releases
You finish with
A percentage rollout that widens in steps

What and why#

What it is#

A rollout turns a feature on for a share of people instead of everyone. You choose a percentage, FlagSwift places each person inside or outside it, and you raise the percentage as confidence grows. Because the decision is made at evaluation time from settings on the server, no deploy is involved: change the number and the next evaluation follows it.

Canary, gradual and scheduled#

Three ways to release
StyleDescription
CanaryA small, deliberate first share, such as 1 to 5 percent, or a named list or segment, kept there while you watch errors and metrics. In the console that is the Rollout percentage with Save changes, or a list under Always on for.
GradualWidening the share in steps, such as 5, 25, 50, 100. You can do each step by hand, or plan all of them as a Progressive rollout release that runs on a timetable.
ScheduledA change that happens at a set time, such as turning the flag on at 09:00 on launch day. Plan it with One change, now or later. See Schedule a change or a staged rollout.

Stickiness and bucketing#

Roll out by decides what is counted: a user, an account or a device. FlagSwift hashes the chosen identifier together with the flag key and maps the result to a bucket from 0 to 9,999. The person is inside the rollout when their bucket is below the percentage times 100. The environment is not part of the hash, so a person keeps the same bucket when a rollout moves between environments, and raising the percentage only ever adds people.

Before you start#

  • A flag with the environment you are releasing in. If you have none yet, follow Create your first flag.
  • The permission to change rollouts there: rollouts.update and flags.toggle. Developers have both outside production but are read-only in production, and Product managers cannot change rollouts at all. In production only a Release manager or an Admin can edit the rollout directly. See Give people the right access.
  • An SDK or API call that sends the identifier you count by: a user, an account or a device identifier. A percentage rollout cannot place a person without one. See Target by person, account, device and attribute.
  • If the environment requires approval, you cannot save a rollout directly: you propose a release instead and a reviewer approves it. See Put production behind review.

Walk through it#

  1. Turn the flag on in the environment

    A rollout only applies while the flag is on. Open Flags and switch the flag on in the environment you are releasing in, either in the table or in the Overview tab of the flag. While it is off, everyone gets the off result with the reason DISABLED, whatever percentage you set.

  2. Pick who the rollout counts

    Open the flag and choose the Targeting & rollout tab. Choose the environment at the top, then find the last numbered step, Everyone else: rollout. Next to Roll out by choose User, Account or Device.

    • User is the default and fits most releases.
    • Account keeps a whole company on the same side, so colleagues see the same thing.
    • Device suits anonymous visitors who have no sign-in.

    Why a person always gets the same answer

    Each person is placed by a stable hash of their identifier and the flag, so raising the percentage only adds people. Nobody who already has the feature loses it. The hash gives each person a position from 0 to 9,999, and the rollout includes everyone whose position is below the percentage times 100, so the percentage is exact to 0.01%.
  3. Start small and save

    Drag the Rollout percentage slider, or type a whole number from 0 to 100 into Exact percentage. Start with a small share such as 5. Choose Save changes at the bottom. Discard drops edits you have not saved.

    Step 5, Everyone else: rollout, at 5 percent. The large figure follows the slider and the box.
    You should see. The large figure beside the step shows the new percentage, the Unsaved changes note disappears, and a new version appears in the History & rollback tab.

    Everyone outside the share keeps the flag's default result, which is off unless you changed the default. A flag with variants serves one variant to each person inside the share, by the weights in the Variants step.

  4. Check who is in

    Open Check who gets this flag at the bottom of the tab, enter a User, Account or Device, and choose Check. It uses the saved settings. See Find out why someone got a result.

    You should see. For a person inside the share you see Served with the reason ROLLOUT_IN and a line such as bucket 312 of 500 (user). For a person outside it you see Not served with ROLLOUT_OUT.
  5. Plan the later steps as a release

    Instead of coming back each time, open the flag's Releases tab and choose Propose release. The Releases page lists releases for every flag but cannot create them. Set the Environment, then set Kind to Progressive rollout and fill in:

    Fields of a progressive rollout
    FieldDescription
    ReasonRequired, up to 200 characters. Reviewers and the audit log show it.
    StagesPercentages separated by commas, such as 5, 25, 50, 100. At least two, at most 20, whole numbers from 0 to 100, each larger than the one before.
    Minutes between stagesAt least 1 and at most 20,160 (14 days). The gap is the same between every stage.
    Turn the flag on with the first stageOn by default. The first stage then sets the percentage first and switches the flag on after, so it never serves the old split.
    Start as soon as it is allowedSwitch it off to choose a Start time in your own time zone. A time in the past means as soon as possible, and a start more than a year ahead is refused.
    ReviewerShown only when the release needs approval. Optional: it asks one release manager or admin, but any of them can still decide.
    Propose a release with Kind set to Progressive rollout. The Reviewer field only appears when the release needs approval.

    Propose release stays disabled until the Reason is filled in and an environment is chosen.

    A release part way through its stages.
    You should see. The release appears in the list with a row of stages. It reads Scheduled and shows when the next stage runs, or Needs approval when a review is required first.
  6. Get it reviewed if required

    A release always waits for review when the environment requires approval, and also when you are a Developer, because only a Release manager or an Admin can approve. The reviewer chooses Approve on the release, and the first stage then runs at its time. The reviewer needs the right to change that environment, since their authority is what applies each stage.

  7. Pull back if something looks wrong

    The person who proposed a release can choose Cancel while it waits or is scheduled. Stages that already ran stay applied. To go further back, use History & rollback, which restores an earlier saved version. To stop the flag for everyone at once, use the kill switch. See Handle an incident with the kill switch.

A missing identifier means nobody is in the rollout

If a request carries no identifier of the kind you roll out by, a percentage rollout cannot place that person and they get the off result with the reason NO_IDENTIFIER. Rolling out by account while your app only sends a user identifier puts nobody in. Only the first identifier of the chosen kind counts.

How the stages run#

  • The server checks for due stages every 15 seconds, so a stage runs within moments of its time.
  • Each stage sets an explicit value, so applying one twice changes nothing.
  • A stage that fails for a temporary reason is tried up to three times, with a growing wait between tries. A refusal does not get retried: it marks the stage Failed and skips the rest.
  • A stage is refused while the kill switch is active in that environment, when the flag has been archived, or when the person the release runs as has lost the permission.
  • After a stage runs, the flag's History & rollback tab shows a new version.

Limits#

Rollout limits
LimitDescription
PercentageA whole number from 0 to 100. 0 serves nobody through the rollout and 100 serves everyone with the reason FULL_ROLLOUT.
Stages in a releaseAt most 20 steps. A progressive rollout needs at least two stages.
Start timeNo more than a year ahead.
Console scheduleThe console makes a single change or a progressive rollout with an equal gap between stages. Steps at unequal times need the API.

Do it with the API#

These are Dashboard API calls. They authenticate with your signed-in session cookie (auth_session), not an API key. Replace the values in capitals.

Set the percentage directly

Needs flags.update plus rollouts.update in the environment. In an environment that requires approval this is refused with APPROVAL_REQUIRED (a 403). Switching the flag on is a separate call and needs flags.toggle: call POST /api/flags/{id}/toggle with { "environment": "production" }, which flips the current state, or let a release set it explicitly with enabled.

Request
curl -s -X PATCH "https://flags.example.com/api/flags/$FLAG_ID/environments/production" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"rolloutPercentage":5,"bucketBy":"user"}'
200 OK (trimmed)
{
  "status": "success",
  "message": "Environment updated successfully",
  "data": {
    "id": "6650c1f2a9b3d4e5f6a7b8c9",
    "name": "checkout-v2",
    "environments": {
      "production": {
        "enabled": true,
        "rolloutPercentage": 5,
        "killSwitchActive": false,
        "version": 12,
        "modifiedBy": "release-manager@example.com"
      }
    }
  }
}

Propose a staged rollout

Needs releases.create. Steps at unequal times are possible here: send steps with a runAt each instead of rollout. The status is pending_approval when the environment requires approval or you cannot review releases, otherwise scheduled.

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": "Checkout redesign, ramp to everyone",
    "rollout": {
      "startAt": "2026-10-05T09:00:00Z",
      "percentages": [5, 25, 50, 100],
      "intervalMinutes": 120,
      "enableFirst": true
    }
  }'
201 Created (trimmed)
{
  "status": "success",
  "message": "Release proposed",
  "data": {
    "id": "6650e3b4c5d6e7f8a9b0c1d2",
    "flagKey": "checkout-v2",
    "environment": "production",
    "title": "Checkout redesign, ramp to everyone",
    "kind": "rollout",
    "status": "pending_approval",
    "requiresApproval": true,
    "nextRunAt": "2026-10-05T09:00:00.000Z",
    "steps": [
      { "index": 0, "runAt": "2026-10-05T09:00:00.000Z", "changes": { "rolloutPercentage": 5, "enabled": true }, "status": "pending", "attempts": 0 },
      { "index": 1, "runAt": "2026-10-05T11:00:00.000Z", "changes": { "rolloutPercentage": 25 }, "status": "pending", "attempts": 0 },
      { "index": 2, "runAt": "2026-10-05T13:00:00.000Z", "changes": { "rolloutPercentage": 50 }, "status": "pending", "attempts": 0 },
      { "index": 3, "runAt": "2026-10-05T15:00:00.000Z", "changes": { "rolloutPercentage": 100 }, "status": "pending", "attempts": 0 }
    ]
  }
}

See Update an environment's configuration and Propose a release for every field.

What to check#

  • The inspector shows the rollout rule and the percentage for a sample identifier.
  • The release lists every stage with its time and whether it has run.
  • Metrics show the flag being evaluated, and Errors stays quiet as the share grows.
  • The flag's Analytics tab shows the split between served on and served off for the environment.

If something goes wrong#

Everyone gets the off result

Why: Check the reason in the inspector. DISABLED means the flag is off in this environment, KILL_SWITCH means an emergency stop is active, and NO_IDENTIFIER means your app does not send the identifier you roll out by.

Fix: Switch the flag on, lift the stop, or send the right identifier.

Save changes is greyed out

Why: Nothing has changed, or a field has an error. The percentage must be a whole number from 0 to 100.

Fix: Edit the value, or read the message beside the field.

Refused with APPROVAL_REQUIRED

Why: The environment requires approval, so direct changes are refused.

Fix: Propose a release from the flag's Releases tab instead of changing it directly.

A Developer cannot save in production

Why: Developers and Product managers are read-only for production changes.

Fix: Ask a Release manager or an Admin, or propose a release.

Each stage must be larger than the one before

Why: The Stages field must climb.

Fix: Write 5, 25, 50, 100 and not 5, 50, 25.

The release shows Failed

Why: A stage was refused (for example the kill switch is active, the flag was archived or the reviewer lost permission) or kept failing. The rest were skipped.

Fix: Open the card: the failed stage shows the reason. Fix the cause, then propose a new release.

The release is still waiting for review days later

Why: A request nobody reviews is cancelled after 72 hours unless the deployment changes it.

Fix: Propose it again and tell your reviewer.

Good habits#

  • Start at 1 to 5 percent and look at errors and metrics before each increase.
  • Give each release a reason that says what you are releasing and why, because reviewers and the audit log show it.
  • Choose Account for anything a team shares, such as a new dashboard, so colleagues never see different versions.
  • Keep the first stage small enough that you can live with a bad result, and leave time between stages for problems to show up.
  • Leave the flag in place at 100 percent until the code no longer needs it, then follow Clean up stale flags.

Good to know#

Lists and segments bypass the percentage

People you name under Always on for, or who are in a selected segment or match a rule, are served the flag whatever the percentage says. A rollout at 0 with a list is a valid canary.
Does lowering the percentage remove people who already have the feature?
Yes, but only the ones at the top of the range. Placement is by bucket, so people with the highest buckets leave first, and going back up brings the same people back.
Why do two flags give different people the feature at 10 percent?
The bucket comes from the identifier and the flag key together, so each flag selects a different 10 percent.
Can I roll out to part of an account?
Not with Roll out by Account: everyone in the account shares one bucket. Roll out by User if people in one account may differ.
How precise is the percentage?
There are 10,000 buckets, so the percentage is exact to 0.01 percent. The console and releases take whole numbers from 0 to 100.