Feature Flags Explained: Safe Releases, Gradual Rollouts and Flag Hygiene

A new checkout flow is ready. Releasing it to everyone at once is risky: if it has a bug, every customer hits it until a fix is deployed. With feature flags, the code goes to production switched off, then turns on for the QA team, then for 5% of users, then 20%, watching error rates at each step. If something goes wrong, one switch returns everyone to the old checkout in seconds.

We wrote a small flag evaluator in Python 3.13 and simulated 10,000 users. The numbers below come from that run. Commercial and open-source flag tools add dashboards, targeting and auditing, but the core logic is similar.

What are feature flags?

A feature flag is a condition in your code whose value comes from configuration instead of being fixed at build time:

def checkout(user):
    return "new checkout" if is_enabled("new_checkout", user) else "old checkout"

Changing the flag’s configuration changes behaviour for chosen users, immediately, without building or deploying anything. Flags are also called feature toggles, switches or feature gates.

Why teams use them

• Separate deploy from release: merge and deploy unfinished work safely, switched off.
• Gradual rollout: limit the blast radius of bugs to a small percentage of users.
• Instant rollback: turn a feature off without a new deployment.
• Trunk-based development: avoid long-lived branches and painful merges, as discussed in merge vs rebase.
• Experiments: show variants to different groups and measure results.

Types of flags

The type decides how the flag should be managed. Release flags should disappear soon after launch; permission flags may live as long as the product does, and are closer to configuration.

How a flag check works

FLAGS = {
    "new_checkout": {"enabled": True, "rollout_percent": 20,
                     "allow_users": ["qa-team-1"], "deny_users": []},
}

def is_enabled(flag, user_id, flags=FLAGS):
    f = flags.get(flag)
    if not f or not f["enabled"]:
        return False
    if user_id in f["deny_users"]:
        return False
    if user_id in f["allow_users"]:
        return True
    return bucket(flag, user_id) < f["rollout_percent"]

The rules are checked in a deliberate order: the master switch first, then explicit deny and allow lists, then the percentage. In our run, the allow-listed QA user always saw the new checkout, while a regular user outside the 20% saw the old one.

Percentage rollouts

20% rollout over 10,000 users: 1986 enabled (19.9%)

Close to the target, as expected from a well-distributed hash. Typical rollout plans move through steps such as 1%, 5%, 20%, 50% and 100%, pausing at each to compare error rates, latency and business metrics between users with and without the feature. Our monitoring vs observability guide covers what to watch.

Stable, sticky buckets

def bucket(flag, user_id):
    h = hashlib.sha256(f"{flag}:{user_id}".encode()).hexdigest()
    return int(h[:8], 16) % 100

Instead of a random number on each request, which would show a user the new checkout on one page and the old one on the next, each user is assigned a stable bucket from 0 to 99 by hashing the flag name and user ID. We checked three properties:

same user always same answer:       True
raised to 50%: 4937 enabled; of the 1986 already in, still in: 1986
different flags pick different users: overlap 57 of 362

The same user always got the same answer. When we raised the rollout from 20% to 50%, every user who already had the feature kept it, because their bucket number did not change; the rollout only added people. And including the flag name in the hash meant two flags at 20% chose largely different users, so the same unlucky group is not the guinea pig for every new feature.

Kill switches and safe defaults

flag off (kill switch):          False
unknown flag defaults to off:    False

Turning enabled off disabled the feature for everyone, including the allow list. That master switch is your emergency brake. Equally important is what happens when the flag service is down, slow or returns an unknown flag. Our evaluator defaults to off, which is usually right for new features. For long-lived ops flags that protect the system, decide deliberately which state is safe. Cache flag values locally so a flag service outage does not take your application down with it.

Testing with flags

test both paths: new checkout / old checkout

Every flag doubles the code paths that can run in production. While a flag exists, test both the on and off states; our quick check exercised both. Inject flag values in tests, rather than reading a live service, so tests are fast and deterministic. Avoid testing every combination of many flags, which grows exponentially; instead, test each flag’s states and the specific combinations that interact. Flags fit naturally with shift-left and shift-right testing: code is tested before merge, then validated with real traffic during a gradual rollout.

Flag debt

Flags are easy to add and easy to forget. Old flags clutter code with dead branches, make behaviour hard to reason about, and occasionally cause disasters when someone flips a flag nobody remembered. Keep it under control:

• Create a removal ticket when you create a release flag.
• Set an expiry date and review expired flags regularly.
• Once a feature is at 100% and stable, remove the flag and the old code path in the next release.
• Track the number of active flags per service and treat a rising count as a warning.

Naming and ownership

Name flags for what they do, such as new_checkout_flow or temp_search_v2_rollout, not flag_17 or test_toggle. A name should make sense to someone reading it six months later. Record an owner, a type and a description for each flag in a central registry, and keep separate values per environment so that turning something on in staging cannot affect production.

Build or buy?

A simple config file or environment variable works for a handful of on/off flags. Once you need percentage rollouts, targeting rules, audit logs, approvals and per-environment control, teams usually adopt a dedicated tool: commercial services such as LaunchDarkly, open-source options such as Unleash and Flagsmith, or the vendor-neutral OpenFeature standard to avoid lock-in. We did not test these products for this article.

Security notes

Flags evaluated in the browser or mobile app are visible to users, who can inspect or change them. Never rely on a client-side flag to protect data or paid features; enforce permissions on the server. Treat changes to production flags like deployments: restrict who can make them, require review for sensitive ones, and keep an audit trail.

A simple rollout runbook

1. Before: merge the code behind a flag that is off; confirm the off path still passes all tests.
2. Internal: enable for the team’s own accounts through the allow list and use the feature for real.
3. Small slice: 1 to 5% of users. Compare error rates, latency and key business numbers with the rest.
4. Grow: step up to 20%, 50% and 100%, pausing long enough at each step to see a normal day’s traffic.
5. Stop rules: agree in advance what triggers a rollback, such as errors above a threshold, and who may flip the switch.
6. Clean up: once stable at 100%, remove the flag and the old code in the next release.

Writing the stop rules down before starting matters most. In the middle of an incident, nobody should be debating whether a 2% error rate is acceptable.

Final thoughts

Feature flags make releases boring in the best way: deploy whenever you like, release gradually, and switch off instantly. Use stable hashing so rollouts are consistent, default safely when the flag system fails, test both sides of every flag, and remove release flags promptly. In our simulation, stable buckets kept every early user enabled as the rollout grew, which is exactly the behaviour users and dashboards depend on.

Frequently asked questions

Keep learning