1. Product introduction

Separate deployment from who sees the feature

PostHog brings product analytics, session replay, experiments and feature flags into one toolkit. Teams can understand how people use a product and choose who gets a new feature first. This article focuses on flags: code may already be deployed, while a flag decision during use controls whether the new experience appears.

Imagine replacing a booking website's three-page form with one page. Releasing it to everyone immediately exposes everyone to submission failures. Starting with staff and expanding gradually offers a smaller setting in which to find problems. Developers must wire both paths into the flag; installing analytics does not create two working versions of a page.

Connect both paths before using evidence from the same population to decide whether to expand. Disabling a flag does not undo submitted bookings. Review branches illustrate a suggested workflow. Enlarge for detail.

2. Core workflow

Connect both the enabled and disabled paths first

Imagine replacing a three-page booking form with a single page. Before using feature flags, developers connect both versions, choose whether decisions apply to users or organizations, and prepare identifiers and event records. Identifiers recognize the same person; events record starting, submitting successfully and encountering errors. Deployment makes the code available, while enabling the feature determines who sees it.

Consistent identity is necessary for a consistent experience. Use a stable ID—a fixed identifier for the same logged-in user. The server must still enforce permissions: hiding a button does not block unauthorized API access. A flag controls feature availability rather than replacing authentication.

Begin with an internal group and observe actual use

  1. Define the first group. The gradual rollout guide starts with yourself, an internal team, test users or organizations. Know who this round affects before changing conditions or percentages.
  2. Check eligibility and the interface. Confirm that intended users see the correct version. The troubleshooting guide describes identity changes, missing stored properties and blocked requests that can affect results. A result still loading also differs from a definite decision not to enable the feature for someone.
  3. Connect behavioral evidence. Follow the same group's entry, form starts and submissions. Use events, recordings and errors to find difficulties instead of relying only on site-wide averages.
  4. Interpret the percentage. The configured percentage is not a quota guaranteed in every small group of visitors. A few visits cannot represent all users.

This turns “how far is it enabled?” into “which people encountered what?” If success and error events are inaccurate, correct the records before interpreting charts.

Decide whether to expand, pause or disable from the evidence

After reviewing this round, increase the audience, continue observing, or disable the new path and fix it. When only the percentage increases and other conditions remain unchanged, fixed assignment rules retain users who already have the feature and may add others. Changing identities or rules removes the basis for that assumption.

Disabling the flag changes subsequent behavior; it does not delete bookings already submitted. Keep the old path working in advance so disabling is a prepared option. Gradual rollout is complete when scope changes have clear audiences, observations and follow-up decisions, not simply when the percentage reaches everyone.

3. Design decisions and takeaways

Give the same person a continuous experience

If every refresh draws a new lottery, the booking form can alternate between one page and three. Users are left wondering what they did wrong. PostHog uses fixed rules and the user’s identifier to decide whether the new feature is available to that person. When only the percentage changes and other conditions stay fixed, increasing it retains users already included and may add users. An empty newly included range can add nobody. The troubleshooting guide describes this behavior.

The design value is reducing an individual's repeated switching. That requires a stable identity first: changing the ID, target entity or rules removes the basis for assuming continuity.

Expanding exposure should widen the circle, rather than reshuffle everyone inside it.

Connect a setting to the people it affects

“Set it to 20%” is a control action. “Can these people complete their booking?” is the product question. Connecting eligibility with events and replay lets a team follow a failed submission back to the experience, rather than rely only on a site-wide average.

Choose the observed population carefully. People who received the new version, people who started using it and people who completed it are different groups. Separating them shows whether a drop happens before entry or during use.

Prepare the way out before opening the new path

Gradual rollout is more than moving a slider forward. Developers need to check that the old path still works when the flag is off. The team needs to know when to hold the percentage and when to stop expanding. A response to trouble then becomes a prepared choice, rather than an improvised repair.

The useful pattern treats release as a series of observable, adjustable decisions. Each change in scope should identify who is affected, the evidence being observed and the next decision.