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#
| Style | Description |
|---|---|
| Canary | A 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. |
| Gradual | Widening 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. |
| Scheduled | A 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.updateandflags.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#
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.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%.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.
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 reasonROLLOUT_INand a line such asbucket 312 of 500 (user). For a person outside it you see Not served withROLLOUT_OUT.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 Field Description Reason Required, up to 200 characters. Reviewers and the audit log show it. Stages Percentages 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 stages At least 1 and at most 20,160 (14 days). The gap is the same between every stage. Turn the flag on with the first stage On 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 allowed Switch 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. Reviewer Shown 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.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.
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
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#
| Limit | Description |
|---|---|
| Percentage | A whole number from 0 to 100. 0 serves nobody through the rollout and 100 serves everyone with the reason FULL_ROLLOUT. |
| Stages in a release | At most 20 steps. A progressive rollout needs at least two stages. |
| Start time | No more than a year ahead. |
| Console schedule | The 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.
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"}'{
"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.
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
}
}'{
"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
Does lowering the percentage remove people who already have the feature?
Why do two flags give different people the feature at 10 percent?
Can I roll out to part of an account?
How precise is the percentage?
Related#
- Targeting and rolloutsHow a flag decides what each person sees.
- Releases and approvalsScheduled changes, staged rollouts and review.
- Schedule a change or a staged rolloutPlan changes for a set time.
- Put production behind reviewAsk for a second pair of eyes first.
- Handle an incidentStop a flag in seconds.