Roll out a feature to the right customer cohort.
Select a stable customer cohort and verify eligibility before exposing the feature. Measure assignment, actual use, correctness, and outcomes separately, then advance or stop through explicit gates that account for already-created state.
Inside this article 7 sections +
Roll out a SaaS feature by selecting a stable customer cohort, verifying its prerequisites, and measuring exposure and business outcomes separately. Advance only when the cohort provides enough evidence and the fallback remains compatible with data already created.
A percentage flag is a selection mechanism, not a rollout strategy. The strategy defines which customers can participate, what the team expects to learn, and when to pause or expand.
Choose the unit that shares the experience
Consider an illustrative collaborative approval feature. If one member sees the new workflow while another member of the same account sees the old one, they may interpret the same approval differently. Account-level allocation is often more appropriate than person-level allocation for a shared workflow.
Use an immutable account identifier and make the allocation stable across requests, devices, and application instances. Do not choose a random variant each time the page loads. Record the flag version or rollout policy associated with important business operations so later investigation can explain which behavior applied.
PostHog supports group-based targeting, and its percentage rollout behavior uses deterministic assignment. Verify the configured entity and supplied group context. A correctly configured account flag can still behave incorrectly if the browser retains a previous workspace's group identity.
- EligibilityReady accounts only
Required schema and account configuration are present.
- ExposureStable account cohort
Members share the intended workflow behavior.
- EvidenceObserve real operations
Track use, correctness, completion, and support friction.
- DecisionAdvance, hold, or stop
Use predeclared gates and compatible recovery paths.
Separate eligibility from percentage allocation
An account may fall into the selected percentage but still lack a required migration, plan capability, or integration version. Evaluate prerequisites before exposure. Keep those conditions visible so a rollout does not appear to reach a cohort that cannot actually use the feature.
The following Python example demonstrates stable account bucketing for an application-owned allocator. It is not an implementation of PostHog's internal hashing and should not be used to predict a vendor's assignments.
import hashlib
import json
def account_bucket(account_id, flag_key, salt):
payload = json.dumps(
[salt, flag_key, account_id],
separators=(",", ":"), ensure_ascii=False
).encode("utf-8")
digest = hashlib.sha256(payload).digest()
return int.from_bytes(digest[:8], "big") % 10000
# Basis points: 500 means a 5% allocation threshold.
def selected(account_id, flag_key, salt, threshold):
return account_bucket(account_id, flag_key, salt) < threshold
Validate threshold inputs and keep the salt stable during a rollout. Increasing a threshold preserves previously selected buckets; changing the salt or identity scheme can reshuffle the cohort. A deterministic sample is approximate at small account counts and does not guarantee that exactly five of every hundred accounts qualify.
Complete prerequisites before exposure
Use backward-compatible data changes while both workflows coexist. Add the new representation, populate required state, and verify reads before exposing writes that old code cannot understand. A flag cannot reverse a destructive schema migration.
Define behavior for an account that loses eligibility after using the feature. A plan change, integration outage, or configuration rollback may make new operations unavailable while existing operations still require completion. Do not hide those operations merely because the entry flag is now off.
Keep authorization separate from feature selection. Being in a rollout cohort does not grant permission to approve a purchase or read private data. The application must enforce the same account and resource rules for both versions.
Measure exposure and value separately
Record when an eligible account actually reaches the feature, not just when it evaluates the flag. A flag evaluation during page bootstrap may happen for accounts that never use the workflow. Distinguish assigned, exposed, started, and completed populations.
Measure correctness and customer outcomes alongside errors and latency. For the approval feature, inspect duplicate decisions, incomplete workflows, time to completion, and support confusion. A low exception rate can coexist with a confusing interface that customers abandon.
Preserve the account and rollout version on relevant events. The account identity guide helps prevent workspace switching from corrupting that evidence. Avoid changing event definitions mid-rollout without marking the discontinuity.
Write stop and advance rules in advance
Define which correctness failures stop expansion immediately and which observations require investigation. Set a minimum observation period or workload coverage appropriate to the feature, including uncommon states and background completion. Do not declare success merely because the first few accounts produced no alerts.
Separate a safety rollout from a controlled experiment. A rollout may deliberately select friendly or low-risk accounts, making its business outcomes unsuitable for a causal comparison with everyone else. Use an experiment design when the question is whether the feature causes an improvement.
The integration kill-switch guide covers stopping authority. A rollout plan additionally needs the route back for already-created state and a decision about when old code can be retired.
Test the flag service being unavailable. Decide whether a previously established account assignment can be reused and how long it remains valid. A default value should preserve a coherent workflow rather than unexpectedly moving an active account between incompatible versions.
Include rollout and handover in the definition of delivery
When buying a feature implementation, specify the first customer cohort and the evidence needed to expand it. Include prerequisite data changes, support instructions, and the person authorized to pause or advance exposure. A feature flag is only one part of this delivery. The team also needs to know whether the old path can read data produced by the new path and how active operations behave when the flag changes.
Ask for an eligibility record, an acceptance fixture set, an outcome view, and a rehearsed stop procedure. Have someone outside the implementation pair follow that procedure in a controlled environment. The handover should explain what the controls can safely stop, what work must finish, and how unresolved customer operations remain visible. These conditions make release readiness inspectable instead of relying on confidence in the deployment.
A scoped implementation can include this complete first rollout and a review point. Continuing delivery support may be useful when exposure depends on customer adoption, several migrations, or a sequence of product decisions. Agree on that responsibility in advance. We can connect the feature, rollout controls, and operating evidence so the buyer receives a usable capability with an understood path to broader availability.
Close the rollout as a product change
After the evidence supports general availability, remove temporary targeting rules and obsolete branches through a reviewed change. Preserve the historical allocation evidence needed to explain earlier behavior. Update support instructions and operating documentation so the feature no longer depends on the original rollout owner.
Software implementation can connect account allocation, migrations, event contracts, and operating gates so gradual exposure produces useful evidence rather than an indefinitely half-released feature.