Guides
Feature flags and rollouts
Release behind flags, roll out gradually, switch off instantly and use remote config.
Create a flag#
Flags → New flag asks for a key (1–64 characters: a-z, 0-9, _, -), a name and a description. Keys can't change later, because your code refers to them. A new flag is a simple on/off flag, switched off in every environment, so creating it changes nothing for users.
The key is filled in from the name as you type and checked on the spot: allowed characters, length, and whether another flag in the project already uses it. A preview shows the variations that will be created and the line of code that reads the flag. ⌘/Ctrl + Enter creates it.
The type on the left sets up common shapes:
- On / off:
off/on, for releases, gradual rollouts and kill switches. - A/B test: control and treatment variations, ready for an experiment.
- AI config:
model,promptandparamsvariables with Off, Current and Challenger variations. See AI configs.
Variations and variables#
Variations → Edit adds, removes and reorders variations, names them, sets each one's on/off state, and manages variables and their per-variation values. Variables are typed (text, number, true/false, JSON) and validated: a number variable can't be given a string.
- Removing a variation that targeting still uses is refused, with the environment and rule named.
- Renaming a variation key rewrites every environment (off and default variation, overrides, rule allocations) in one step. It's refused while the variation is in a running experiment, because its exposures are recorded under the old key. Code that compares
variationKeymust change too, which is why reading variables is preferred.
Targeting per environment#
Open a flag and pick an environment. The editor shows, in evaluation order:
| Setting | What it does |
|---|---|
| On / off | The kill switch. Off serves the off variation to everyone, immediately. |
| User overrides | User id → variation. Checked before rules; ideal for QA, demos and allowlists. |
| Rules | Top to bottom. The first rule whose conditions match and whose traffic includes the user decides. Drag to reorder. |
| Default variation | Served when the flag is on but no rule took the user. Defaults to the off variation. |
Rules#
A rule has conditions (empty = everyone; built with the same editor as audiences), a traffic percentage and a split across variations. The editor checks that the split adds up to 100% as you type. Conditions that the visual editor can't show open as JSON, so nothing is ever lost.
Each rule has a server-generated salt that never changes, so editing or renaming a rule never reshuffles users. Raising traffic only adds users; those already in keep their variation.
Gradual rollouts#
To release safely, add a rollout rule that gives on to a growing share of users:
- Start at 5% for internal users (an audience such as
email ends with @yourcompany.com), then 5% of everyone. - Raise it to 25%, 50% and 100% as error rates and support tickets stay flat.
- If something goes wrong, switch the flag off: everyone gets the off variation within the SDK's refresh time, with no deploy.
Kill switches#
The flag list has an on/off switch per environment. Production-like environments ask for confirmation first. From the API:
curl -X POST https://api.liftcanary.com/v1/projects/web/flags/new_checkout/environments/production/toggle \
-H "Authorization: Bearer $LIFTCANARY_TOKEN" -H "Content-Type: application/json" \
-d '{"enabled": false}'Saving safely with teammates#
Every save sends the version of the configuration you started from. If a teammate saved in the meantime, your save is refused with a prompt to reload instead of silently overwriting their change. API clients get the same protection with If-Match; see API overview.
Reading flags in code#
user.isEnabled("new_checkout"); // boolean: is the feature on?
user.getVariable("new_checkout", "button_text", "Buy now"); // typed variable with a fallback
user.decide("new_checkout"); // full decision: variation, rule, reason, variablesThe website snippet has the same calls on window.liftcanary (isEnabled, variable, decide); React Native has hooks. Details per platform are in the SDK reference.
Archiving#
When a flag is fully rolled out, remove it from your code first, then archive it (Delete in the dashboard, DELETE …/flags/:flag in the API). Archived flags disappear from datafiles; code that still asks for one gets FLAG_NOT_FOUND and your fallback values.