> ## Documentation Index
> Fetch the complete documentation index at: https://docs.growthbook.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Feature Flag Rules

> How rules override a feature's default value — targeting users, rolling out gradually, experimenting — and how to scope, ramp, and schedule them.

Every feature has a [default value](https://docs.growthbook.io/features/basics.md#default-values) that applies to all users. **Rules** override that default for the users, environments, and projects you choose.

## How Rules Work

A feature's rules are an ordered list. For each request, GrowthBook evaluates them top to bottom and the **first matching rule wins**. If no rule matches, the default value is used.

![Feature rules interface](https://mintcdn.com/growthbook-ea15456d/giSZyh24PfnTkKz4/static/images/features/feature-override-rules-2.png?fit=max\&auto=format\&n=giSZyh24PfnTkKz4\&q=85\&s=47397509c3e5e3cca31d6c37a832b9dc)

Each rule has up to four parts:

* **Targeting conditions** define *who* the rule applies to. Conditions are evaluated against the [attributes](https://docs.growthbook.io/features/targeting.md) you pass into the SDK. A rule with no conditions applies to everyone.
* **What it does** for matching users — serve a value, run an experiment, or run a bandit.
* **Scope** — which [environments](#environments) and, optionally, which [projects](#projects) the rule applies to.
* **Release plan** (optional) — a value-serving rule can [ramp up automatically](#ramp-ups-and-safe-rollouts) over time instead of switching on all at once.

> [!TIP]
>
> **Rules can be combined**
>
> Layer multiple rules on one feature to compose behavior — for example, a forced value for beta testers above a gradual rollout to everyone else.

## Rule Types

| | Targeting rule | Experiment | Bandit |
| - | - | - | - |
| **Purpose** | Serve a value to matching users | Measure which value performs best | Auto-optimize toward the best value |
| **Randomization** | Optional (percentage rollout) | Random split | Random split, reweighted over time |
| **Tracking** | No | Yes | Yes |
| **Typical use** | Enable for a group; gradual release | A/B test a change | Maximize a metric across several options |

Gradual ramp-ups and guardrail-monitored "safe" rollouts are **not** separate rule types — they're [release plans](#ramp-ups-and-safe-rollouts) you add to a targeting rule.

### Targeting Rule (forced value or percentage rollout)

The most common rule serves a single value to the users who match its conditions. In the rule editor it appears as two presets of the same rule:

* **Forced value** — everyone who matches gets the value.
* **Percentage rollout** — a random sample gets the value and the rest fall through to the next rule. A forced value is simply a 100% rollout.

![Forced value rule UI](https://mintcdn.com/growthbook-ea15456d/giSZyh24PfnTkKz4/static/images/features/feature-force-rule-2.png?fit=max\&auto=format\&n=giSZyh24PfnTkKz4\&q=85\&s=36f605dd49b3c66984209688d54fb3fa)

For a percentage rollout, choose a user attribute (e.g., `id` or `company`) to sample on. Users with the same attribute value always get the same experience — choosing `company`, for example, keeps everyone at a company on the same side of the rollout.

![Percentage rollout UI](https://mintcdn.com/growthbook-ea15456d/1rsmujQCDzXz2Vho/static/images/features/feature-rollout-rule-2.png?fit=max\&auto=format\&n=1rsmujQCDzXz2Vho\&q=85\&s=65a854e46dcd08f2cd0360e5907a2f36)

Common scenarios:

* Turning a feature on for internal employees or beta testers
* Overriding a value for a single account that reported a bug
* Releasing to 10% of users, then 50%, then 100%

To widen a rollout **automatically** instead of editing the percentage by hand, add a [Ramp-up release plan](#ramp-ups-and-safe-rollouts).

### Experiment

Experiment rules randomly split users into variations, assign each variation a value, and log every assignment through the SDK's `trackingCallback` so you can measure impact in your data warehouse or analytics tool.

![Experiment rule UI](https://mintcdn.com/growthbook-ea15456d/giSZyh24PfnTkKz4/static/images/features/feature-experiment-rules-2.png?fit=max\&auto=format\&n=giSZyh24PfnTkKz4\&q=85\&s=724fb2f5c8680a16d44420836a0371f2)

You control both the percentage of users included and the split between variations. For example, including 50% of users with a 40/60 split means 20% of all users see variation A, 30% see variation B, and the remaining 50% fall through to the next rule.

→ [Full experimentation documentation](https://docs.growthbook.io/features/feature-flag-experiments.md)

### Bandit

A [Bandit](https://docs.growthbook.io/bandits/overview.md) rule works like an experiment but **automatically shifts traffic toward the better-performing variation** as results come in, rather than holding a fixed split. Use it to optimize toward a metric across several options instead of measuring one change precisely.

> [!NOTE]
>
> [**Contextual Bandits**](https://docs.growthbook.io/bandits/contextual.md), which choose a variation per user based on their attributes, are in beta.

## Ramp-ups and Safe Rollouts

Pro

**Ramp Schedules**
is available on Pro and Enterprise plans.

A **Ramp Schedule** is a release plan you attach to a value-serving (targeting) rule — not a separate rule type. Choose **Ramp-up** as the rule's release plan to roll out in timed, optionally approval-gated stages that advance on their own (for example, 1% → 5% → 25% → 100%). You widen exposure gradually and can stop early if something looks wrong. This is the modern replacement for manually bumping a rollout percentage.

→ [Ramp Schedules](https://docs.growthbook.io/features/ramp-schedules.md)

**Safe Rollout** is the same mechanism with **guardrail monitoring** turned on: GrowthBook runs the ramp as a short A/B test against your guardrail metrics (error rate, latency, conversions, …) and flags regressions so you can roll back. If you've used a standalone "Safe Rollout" rule before, it's now a monitored ramp-up rather than its own rule type.

→ [Safe Rollouts](https://docs.growthbook.io/features/safe-rollouts.md)

## Scoping Rules

### Environments

Each rule applies to **all environments or a specific set**, chosen in the rule's environment scope. Because each [SDK connection maps to one environment](https://docs.growthbook.io/features/environments.md#environments-and-sdks), this controls where a rule actually takes effect — letting you test a rule in `dev` before enabling it in `production`.

### Projects

A rule can optionally be scoped to specific **projects** within the feature's delivery set — an advanced way to run a rule in only some of the projects a multi-project feature reaches. A rule left unscoped applies to all of them; a rule scoped to a project the feature isn't delivered to won't take effect (the editor flags it).

→ [Delivering a feature to multiple projects](https://docs.growthbook.io/features/environments.md#delivering-a-feature-to-multiple-projects)

### Requiring a scope

Turn on **Require rules to target specific environments or Projects** under **Settings → General → Feature Flags** to stop rules from quietly applying everywhere. Saving a new rule for All Environments and All Projects, or widening an existing rule to that, then shows a warning you have to acknowledge before the rule saves. Rules that already apply everywhere can still be edited.

Over the REST API, those writes return a `422` with code `unscoped_rule`. Send `"allowUnscopedRules": true` in the request body to save the rule anyway. A key with confirmation rules for overrides holds that request until a person confirms it.

## Scheduling Rules

Pro

**Schedule Feature Flag**
is available on Pro and Enterprise plans.

Any rule can be scheduled to turn on or off at a specific date and time — useful for launches, holidays, or special promotions.

![Feature Scheduling](https://mintcdn.com/growthbook-ea15456d/1rsmujQCDzXz2Vho/static/images/features/feature-scheduling-2.png?fit=max\&auto=format\&n=1rsmujQCDzXz2Vho\&q=85\&s=32e660eafa875484b78aa60266955e25)

For a multi-stage rollout that advances automatically, use a [Ramp Schedule](#ramp-ups-and-safe-rollouts) instead.

## Targeting Conditions

Any rule can include targeting conditions to limit which users it applies to. Conditions you define in GrowthBook are evaluated against the attributes you pass into the SDK.

![Rule conditions UI](https://mintcdn.com/growthbook-ea15456d/1rsmujQCDzXz2Vho/static/images/features/feature-rule-conditions.png?fit=max\&auto=format\&n=1rsmujQCDzXz2Vho\&q=85\&s=5366c21e435b271ed3ad338004959e3d)

→ [Full targeting reference: attributes, conditions, and saved groups](https://docs.growthbook.io/features/targeting.md)

## Testing Rules

Test your rules directly in GrowthBook on the **Simulation** page. Adjust user attributes and see in real time which rules match and what value the user would receive.

<video autoPlay loop muted controls allowFullScreen>
  <source src="https://mintcdn.com/growthbook-ea15456d/66H-dO8hZfIFVUdN/static/videos/feature-test-rules.mp4?fit=max&auto=format&n=66H-dO8hZfIFVUdN&q=85&s=a0bee986fa7523ebfd42be1064ffc4b3" type="video/mp4" />
</video>

### Archetypes

Pro

**Archetypes**
is available on Pro and Enterprise plans.

Archetypes let you save preset user attribute profiles so you can quickly test how rules apply to specific types of users. If you frequently target features to certain groups (e.g., beta testers, enterprise accounts), archetypes let you check the result in one click. They appear at the top of the **Simulation** page. Hover over any value to see debug information.

![Archetypes](https://mintcdn.com/growthbook-ea15456d/giSZyh24PfnTkKz4/static/images/features/feature-archetypes-2.png?fit=max\&auto=format\&n=giSZyh24PfnTkKz4\&q=85\&s=de2d6729f26a6d3684d71397942f1bf5)

Create and manage archetypes by navigating to **SDK Configuration** → **Archetypes**.