Configure rollout percentage for gradual feature enablement

When configuring a feature flag, administrators can set a rollout percentage (0–100%) in addition to the binary on/off state. The rollout-evaluator uses a deterministic hash of the user's identifier and the flag key to consistently assign each user to either the enabled or disabled cohort. This ensures the same user always sees the same experience for a given rollout percentage, avoiding flickering. The percentage can be increased incrementally (e.g., 10% → 25% → 50% → 100%) as confidence grows.

MEDIUM story-organization-scoped-feature-flags-coordinator-004 8 pts

Story Points

Medium

Priority

Organization-scoped Feature Flags

Feature

User Story

As a Coordinator

I want to enable a feature for a percentage of users in my organization before full rollout

So that I can test new features like gamification or scenario-based notifications with a small subset of peer mentors before exposing them to the entire organization, reducing the risk of disruption

Acceptance Criteria

Given I am on the feature flag admin screen, when I open the configuration for a flag, then I can set a rollout percentage between 0 and 100
Given I set a rollout percentage of 20%, when the rollout-evaluator determines feature visibility for a user, then approximately 20% of users in my organization consistently see the feature enabled
Given a user is assigned to the enabled cohort at 20% rollout, when the percentage is later increased to 50%, then that user remains in the enabled cohort (deterministic assignment)
Given a rollout is set to 0%, when any user in the organization opens the app, then the feature is not visible regardless of the flag's enabled state
Given a rollout is set to 100%, when any user in the organization opens the app, then the feature behaves identically to the flag being fully enabled
Given the rollout percentage is updated by an administrator, when the feature-flag-cache is invalidated, then the next flag evaluation uses the updated percentage

Business Value

Gradual rollout reduces the risk of introducing new features to all 380+ active users at once. All three organizations explicitly requested incremental rollout ('introduce as an offer, not a mandate'). Percentage-based rollouts allow product teams to gather feedback from a small pilot group, validate reliability with real workloads, and increase confidence before full deployment — directly supporting the TestFlight pilot strategy.

Components

Organization-scoped Feature Flags

Related Feature

Coordinator

User Role