Gradual Rollout

Goal: Release a new feature to a small percentage of users, monitor for issues, then expand to everyone — all without redeploying.

When to use this

Use gradual rollout when you want to reduce the blast radius of a new feature. Instead of exposing 100% of users to a potentially broken change, you start at 5–10%, watch error rates, then expand.

How percentage rollout works

ReleaseAnchor hashes a combination of the user identifier and the flag key to produce a number between 0 and 99. If that number falls below the threshold (e.g. 20 for a 20% rollout), the flag returns true.

This means:

The same user always gets the same result (deterministic)
A user in the 10% cohort stays in it when you expand to 50%
Distribution is uniform — you're not just picking the first 10% of users by ID

Step-by-step

1
Create or select your flag
In the dashboard, go to Flags and select the flag you want to roll out (or create a new one).
Make sure the flag is disabled in Production — you'll enable it only through the percentage rule.
2
Add a percentage rule
On the flag's detail page, click Rules for the Production environment.
Click Add Rule → select Percentage rollout.
Set the threshold to 10 (10% of users) and the serve value to true.
Click Save.
3
Add a static fallback rule (optional)
Optionally, click Add Rule → select Static and set serve value to false.
This makes the fallback explicit — users outside the 10% bucket get an intentional false rather than the implicit default. It is not required; the flag already returns false for non-matching users with or without this rule.
1. Percentage: 10% → true 2. Static: always → false ← optional
4
Enable the flag
Toggle the Production environment switch to Enabled.
Rules only apply when the flag is enabled. If the flag is disabled, all users get false regardless of rules.

Verify

Test with a few user IDs to confirm some get true and most get false:

for id in user-001 user-002 user-003 user-004 user-005; do
  echo -n "$id: "
  curl --location 'https://api.releaseanchor.com/v1/evaluate' \
    --header 'Content-Type: application/json' \
    --header "Authorization: ApiKey $RELEASE_ANCHOR_KEY" \
    --data '{"flagKey":"new-checkout","userIdentifier":"'"$id"'"}' \
    | jq .value
done

6
Expand the rollout
Once you're confident (no error rate increase, metrics look good), increase the percentage.
Go back to the Rules tab → edit the percentage rule → change 10 to 50 → Save.
Repeat: 50% → 100%.
7
Clean up
Once you're at 100% and have been stable for a release cycle, delete the rules and leave the flag enabled (or remove the flag evaluation from your code entirely).
This keeps your flag list clean and avoids dead code.

Tips

Start lower than you think you need. 5% is fine for a first rollout. You can always increase it.

Watch your error rates. Before expanding, check your error monitoring for any spike in the affected code paths.

Use the same user identifier consistently. If you sometimes pass userId and sometimes email, the same person might get different results. Pick one and stick to it.

Don't use percentage rollout for feature announcements. If you're telling users "this feature is coming soon," a user who got true yesterday shouldn't get false today. Percentage rollout is stable, but only if the flag threshold doesn't decrease.

Was this helpful?