Rollout Strategies & Percentage Rollouts

Rollout strategies determine how variations are distributed to users. Featureflip supports two strategies: fixed serving and percentage rollout. You can use them independently or combine them with targeting rules.

Fixed serving

With fixed serving, every user who matches a rule (or reaches the fallthrough) gets the same variation. There is no randomness or splitting.

This is the default strategy and the simplest to reason about:

• Rule matches “enterprise” users — all enterprise users get true
• Fallthrough — everyone else gets false

Fixed serving is the right choice when you want a binary decision: a group of users either gets the feature or they do not.

Percentage rollout

With percentage rollout, traffic is split across variations by percentage. For example:

• true — 20% of users
• false — 80% of users

This is useful for gradual rollouts (test with a small group before going wide) and A/B testing (compare two or more variations against each other).

You set a percentage rollout on a targeting rule. To roll out to everyone, use a rule with no conditions, which matches every visitor who reaches it.

How percentage rollout works

Featureflip puts each visitor in a bucket with a deterministic hash:

1. The rule’s Bucket by attribute (user_id unless you change it) is combined with the flag’s stable salt and hashed.
2. The hash gives a number from 0 to 99.
3. That number picks the variation, according to the percentages you set.

Hashing the same value gives the same bucket every time, so a visitor keeps their variation for a given flag across refreshes, sessions and API calls.

Each flag has its own salt. Being in the 20% for one flag says nothing about where someone lands for another.

Choosing what to bucket by

Every rollout rule has a Bucket by setting, just under the percentage slider in the rule editor. It names the context attribute the hash reads. Most flags should keep the default, user_id (userId is accepted as an alias). Change it when the stable value you have is something else:

• Logged-out traffic on your server. Code that serves anonymous visitors has no user ID, but it usually has an anonymous ID from a cookie or a device. Bucket by that attribute, anonymous_id say, and those visitors get a sticky rollout too.
• Something other than a person. Bucket by accountId or teamId and everyone in one account sees the same variation.

The editor suggests attribute names your project already uses in rules and segments. Type the name exactly as your SDK sends it, case included. The management API (bucketBy on a rule) and the MCP server can set it as well.

Changing Bucket by reshuffles the rollout

Raising or lowering the percentage leaves everyone in place. A new attribute means every visitor is hashed again on the new value, so some who had the variation lose it and others gain it, which is why it’s worth settling on the attribute before the rollout starts.

Visitors without the attribute

A context that doesn’t carry the rule’s Bucket by attribute can’t be bucketed, and neither can one where it’s empty, or a list or an object rather than a single string, number or boolean. Featureflip skips that rule. The visitor moves on to the next rule, or gets the flag’s default variation if nothing else matches, and this holds for any rule with a rollout, including one set to 100% through the API. (In the dashboard, dragging the slider to 100% turns the rollout off, and the rule then serves everyone it matches.)

Where the stable value comes from depends on where you evaluate:

Where you evaluate	How visitors stay in their bucket
Browser, React and mobile SDKs	The SDK creates an anonymous user_id on first use and keeps it, so the default user_id works with no setup. If you pick a different attribute, put it in the context yourself.
Server SDKs	Pass the signed-in user’s ID. For logged-out traffic, pass a stable anonymous ID as an attribute and set Bucket by to it.
Evaluation API over HTTP	/v1/client/evaluate takes a flat context: send user_id, or the Bucket by attribute. /v1/sdk/evaluate takes context.userId and context.attributes: send userId, or put the Bucket by attribute under attributes. A request with neither skips every rollout rule.

Before you ship, try a context in the flag’s Evaluate dialog. If it lacks the attribute, the rollout step says the rule was skipped and names the attribute it wanted.

SDK versions for a custom Bucket by

Server SDKs evaluate flags in your process, so the skip rule above needs an SDK version that knows it. Older versions give every visitor without the attribute the same variation instead of skipping the rule, and can hash a boolean value differently. The default user_id isn’t affected. Before you set a custom Bucket by, check that your services run at least:

SDK	Minimum version
Node.js	@featureflip/node 2.15.0, with @featureflip/js 2.15.0 or later (it does the evaluation)
Cloudflare Workers	@featureflip/edge 2.15.0
Python	2.9.0
Java	2.12.0
.NET	2.11.0
Go	2.10.0
PHP	3.6.0
Ruby	2.12.0

The OpenFeature providers use these SDKs, so the same versions apply underneath them. Browser, React and mobile SDKs are evaluated by Featureflip’s servers and work with any version.

Spotting a rollout nobody reaches

A mistyped Bucket by fails quietly, and the rule serves nobody. The flag’s Analytics tab catches this. It warns on a live rollout rule that got no evaluations while at least 100 reached the flag’s rules, once the rule has gone a day without changes. Three causes cover almost every case you’ll see: a context that doesn’t send the attribute, conditions that never match, or an earlier rule that catches the traffic first. The API’s flag evaluations response carries the same check as rollout.unreached.

Gradual rollout pattern

The most common use of percentage rollout is a gradual feature release:

1. 5% — Release to a small group. Monitor error rates and key metrics.
2. 25% — Expand if metrics look healthy. Watch for edge cases.
3. 50% — Half of users now have the feature. Continue monitoring.
4. 100% — Full rollout. The feature is live for everyone.

At any step, if you see problems, reduce the percentage back down or set it to 0%. There is no deployment involved — the change takes effect within seconds.

Once a feature is at 100% and stable, remove the flag from your code and delete it from Featureflip. Stale flags add complexity.

For more on the rollout ladder, what to monitor at each step, common pitfalls, and when not to reach for a percentage gate, see Progressive rollouts with feature flags.

Combining strategies

Targeting rules and rollout strategies work together. A common pattern:

• Rule 1: email ends with "@yourcompany.com" — serve true (fixed). Your internal team always sees the feature for dogfooding.
• Rule 2: Segment "Beta Users" — serve true (fixed). Beta testers always see the feature.
• Rule 3: no conditions, 10% rollout of true. A small slice of everyone else also sees the feature.
• Fallthrough: false. Visitors outside Rule 3’s 10% get the default variation.

Rules are evaluated top to bottom, and a visitor gets the variation of the first rule that matches. Rule 3 matches everyone the first two rules didn’t, and its rollout picks the 10%.

This lets you guarantee access for specific groups while gradually exposing the feature to the broader user base.

Next steps

• Progressive rollouts with feature flags — the rollout ladder, monitoring at each step, and common pitfalls
• Targeting & Segments — attribute-based targeting and reusable segments
• How to Set Up Targeting Rules — step-by-step guide to configuring rules and rollouts
• How to Use Segments — create reusable user groups
• Evaluation API — see how rollouts are resolved via the REST API

Frequently Asked Questions

What is a percentage rollout?

A percentage rollout splits traffic between variations by weight, say 20% of users on the new behavior and the remaining 80% on the current one. Assignment is deterministic. Featureflip hashes the user’s ID together with a stable per-flag salt, so a given user lands in the same bucket on each page load and API call, and on any device that sends the same ID. Widen it to 50% and everyone already in stays in. Each flag hashes separately, so being in one flag’s 20% says nothing about the next.

How do I gradually release a feature to users?

Start at 5%. Watch error rates, latency and whichever business metric the feature touches. Give it a day or two. If the numbers hold, go to 25%, then 50%, then 100%, and if something looks wrong, drop back to 0%, a change that reaches every running instance within seconds with no deploy. Because bucketing is deterministic, users who already have the feature keep it as the percentage climbs. At 100%, delete the flag from your code. Archive it in Featureflip only after that change is live in production.

What is a canary release in feature flags?

A canary release puts a new feature in front of a small group first, so problems show up while only a few people can hit them. Miners once carried canaries to warn of gas, hence the name. Featureflip canaries stack two layers. A targeting rule serves the feature to your own staff or beta testers every time, and a last rule with no conditions runs a small percentage rollout, around 2–5% of everyone else. If errors climb in that group, set the percentage to zero. Otherwise, raise it in steps.