How to roll a feature out gradually

A gradual rollout gives a new feature to a few people first, then to more, then to everyone. You watch how it goes at each step and move at your own pace. Feature flags make this a setting you change, not a release you ship.

This guide walks through a rollout from the first tester to 100%, using the Flagbearer CLI: one command in your terminal for each step. Everything here also works from the dashboard, with a switch and a slider.

Before you start: set up the CLI

Install the CLI, sign in through your browser, and pick the app you're working on:

npm install --global @flagbearer/cli
flagbearer login
export FLAGBEARER_APP=storefront

flagbearer apps list shows your apps. With FLAGBEARER_APP set, the commands below don't need an --app option each time.

1. Put the feature behind a flag

A feature flag is a named switch your code checks. Create one from your terminal:

flagbearer flags create new-checkout

Then check it in your app, where the new feature starts:

if (flags.isEnabled("new-checkout", false)) {
  showNewCheckout();
}

The false is the default: what the app does until the flag is turned on. Ship this code whenever it's ready. Nobody sees the feature yet.

2. Start with your testers

Turn the flag on for your team before anyone else. In Flagbearer, each environment has a list of testers, by email, and testers always get a flag when it's on. With the rollout at 0%, they're the only ones who do.

flagbearer flags set new-checkout --env production --rollout 0

The CLI asks you to confirm a change to production, so a mistyped command can't change it by surprise.

Now your team uses the real feature, in production, with real data.

3. Grow by percentage

When the team is happy, give the feature to a small share of users, then a larger one:

flagbearer flags set new-checkout --env production --rollout 5
flagbearer flags set new-checkout --env production --rollout 25
flagbearer flags set new-checkout --env production --rollout 50

Each change reaches your users within seconds, with no redeploy. The same people stay in as the number grows: someone who got the feature at 5% still has it at 25%, so nobody sees it come and go.

How long to stay at each step is up to you. A common rhythm is a day at each, with a look at your metrics and your support inbox in between.

4. Reach everyone

Set the rollout to 100 and the launch is done:

flagbearer flags set new-checkout --env production --rollout 100

You can change the number at any point along the way, in either direction. flagbearer flags list shows every flag with its rollout in each environment.

See what one user got

During a rollout, people ask "does this customer have the new checkout?" The CLI answers by email or user key:

flagbearer users flags jane@example.com --env production

It lists every flag for that user, on or off. To see what they had at a moment in the past, such as when they wrote in, add a time. Add two to see what changed in between:

flagbearer users flags jane@example.com --env production \
  --at "2026-11-04 14:05" --at "2026-11-05 09:00"

5. Tidy up

Once the feature has been at 100% for a while, remove the check from your code and delete the flag. Flags are for change in progress, and a short list of them is easier to work with.

Rolling out from CI or an agent

The same commands run in a deploy job. The CLI docs show a GitHub Actions step that starts a rollout after each deploy.

You can also hand the whole thing to an AI agent, which creates the flag, writes the code that checks it and changes the rollout when you ask. See set up feature flags with an AI agent.