How to Do a Percentage Rollout With Feature Flags

A percentage rollout enables the flag for a stable slice of users, which you grow from 1% toward 100%.

Percentage rollouts hash a stable key into buckets and enable the flag for the chosen fraction. Because bucketing is deterministic, the same users stay enabled as you raise the percentage.

Steps

Choose a stable bucketing key (user id, account id).
Set the rollout percentage on the flag.
Raise the percentage in steps while watching metrics.

Percentage rollout

flags.yaml

flags:
  new-checkout:
    defaultVariation: false
    rollout:
      bucketBy: userId
      percentage: 10   # 10% see the feature

Advance the rollout

Terminal

# Terminal: widen exposure in steps
flagctl update new-checkout --rollout 25
flagctl update new-checkout --rollout 50

Gotchas

Bucketing by a random value reshuffles users each request; use a stable key.
Changing the bucketing key mid-rollout moves users in and out of the feature.