What a plan controls
A plan belongs to one feature flag and contains ordered stages. Every stage combines a trigger, one or more actions, an audience, target environments, and safety gates. Environment choices are explicit: changing Dev never implicitly selects or changes Production.
Time, elapsed duration, usage threshold, lifecycle state, or approval.
Named environments plus everyone or a context-matched audience.
Atomic changes protected by validation, approvals, versions, and deadlines.
Built-in scenarios
Tiles are editable starting points. Selecting one always creates a new unsaved draft with fresh plan and stage identities; it never modifies a stored plan.
| Template | Default journey | Typical use |
|---|---|---|
| Scheduled activation | Enable one environment at a future time. | Coordinated and embargoed launches. |
| Progressive rollout | Ramp 10% → 25% → 50% → 100%. | Limit blast radius while observing health. |
| Environment rollout | Copy Dev → Test → UAT → Production, optionally starting a guarded rollout after each promotion. | Create missing destination configurations and move a proven release forward. |
| Traffic threshold activation | Count unique users in one environment, then enable the flag. | Wait for real traffic before activating an off flag. |
| Regional launch | Enable and target a region context value. | Market-by-market expansion. |
| Temporary flag | Enable, then disable after a duration. | Campaigns and temporary access. |
| Release retirement | Notify when stale, then archive after approval. | It does not schedule a calendar removal unless you also fill in Schedule flag removal. |
| Custom automation | Choose the trigger, action, environments, audience, rollout safety, expiration, notification, or archive behavior. | Workflows that do not fit a single-purpose template. |
Flag Automations: 101
- Runs automatically: An automation plan runs on its own unless a stage requires Admin Approval.
- Pre-approve the whole plan: If a stage requires Admin Approval, you can grant that approval up front under Planned Events, covering every stage the flag runs under. A plan created or edited by an Admin is pre-approved automatically the moment it's saved.
- Your changes suspend the plan right away: Changing an environment a running plan still controls suspends that plan the moment you save, so its next step can never overwrite your change. The flag itself is not placed in a suspended lifecycle state. See Editing a flag that automation controls below.
- Status changes can cascade: When an automation plan changes one flag's status — for example a "parent" flag becomes active — dependent flags are reevaluated, which can trigger a chain of evaluations that changes the state of other flags.
- Every change is broadcast and logged: Webhooks, streaming, and other subscribers receive each flag's newly evaluated status, and the event log is updated to reflect it.
- Grant or revoke approval anytime: You can grant or revoke an automation plan's approval before it executes or while it's executing — either way, the plan will never compromise the security settings you've put in place for your environments.
Choose the right workflow
Templates are complete, editable plans rather than one-click commands. Review the generated stages, target environments, dates, approval gates, and safety settings before activation.
Scheduled activation
Turns the flag on in every selected environment at one future date and time. Use it for coordinated launches, embargoes, or a release that must begin outside working hours. Scheduling accepts the current time or a future time; past dates are rejected.
Gradual rollout
Raises one environment through ordered percentage steps such as 5%, 25%, 50%, and 100%. Each value must be unique, between 1 and 100, and greater than the previous value. Presets provide safe starting points, and Add step inserts another valid percentage.
The step duration controls soak time. The active view shows the serving percentage, journey, elapsed time, next step, activity, and past rollout attempts.
Environment rollout
Copies the source configuration into the first destination, then uses each successful destination as the source for the next hop. A destination does not need an existing flag configuration: promotion can create it, subject to environment policy and approval.
Choose immediate 100% release or enable Gradual rollout after promotion. In that mode, each promotion creates a second guarded rollout task in the newly promoted environment before the journey continues.
Traffic threshold activation
Counts distinct users who evaluate the flag in the selected environment after the automation starts. Once the threshold is reached, it enables an off flag without changing its configured rollout percentage.
If the flag is already on: reaching the threshold leaves serving unchanged. Use Gradual rollout when the desired outcome is to increase exposure.
Regional launch
Writes a targeting rule for an exact context field and one or more accepted values, such as State = Cali. Matching users receive the selected variant; everyone else receives the fallback. Use the same field name and value shape that your application sends during evaluation.
Temporary flag
Enables the flag at the chosen time and disables it after the configured duration. It is useful for events, trials, maintenance windows, and time-boxed access. Disabling is not archiving: the flag remains available for later use.
Release retirement
Waits until a fully released flag becomes stale, notifies its owners, requests approval, and archives it. Use this for cleanup after the release is permanent. A separate Schedule flag removal date is required if you want the lifecycle to show Removal scheduled before archival.
Custom automation
Builds one explicit operation: promote configuration, turn on or off, start a gradual rollout, update targeting, set expiration, notify, or archive. Then choose what triggers it: time, elapsed duration, evaluation count, unique users, lifecycle state, or approval.
Add context condition scopes a targeting action by evaluation data your application supplies. It does not query a customer database. For example, field State with value Cali matches only evaluations carrying that exact attribute; matching and fallback variants determine what each audience receives.
Editing a flag that automation controls
A flag stays editable while automation runs, so anyone can turn it off or change a rollout during an incident without first finding the plan. When you change an environment a running plan still controls, the plan is suspended as you save. It never changes that environment again until someone resumes it, so your change can't be overwritten.
| What you do | What happens |
|---|---|
| Change rollout, rules, fallback variant, or end of enrollment in a controlled environment | You're asked first: This pauses 'Checkout rollout'. It won't change PRODUCTION again until someone resumes it. Choose Save and pause or Cancel. On save, the plan shows Suspended with who changed what, for example Paused because alice@example.com changed PRODUCTION rollout. |
| Turn the flag off (kill switch) | One click, no question. The flag turns off and the plan is suspended with the reason. |
| Turn the flag on, promote into, or remove the flag from a controlled environment | The same confirmation, then the change saves and the plan is suspended. |
| Edit the description, tags, owner, or an environment the plan doesn't use | Nothing is paused and nothing is asked. |
| Make a change that needs approval | Nothing pauses while the request waits. The plan is suspended when an administrator approves the change, because that is when it takes effect. |
| Change configuration through the Management API | The plan is suspended the same way, without a confirmation. The reason says a Management API key made the change. |
| Save without changing anything in the environment | Nothing is paused. |
Suspended versus Errored
Suspended (yellow) means a person stopped the plan, by pressing Suspend or by changing an environment it controls. Nothing broke. Errored (red) means a step could not run, for example a telemetry deadline passed; the reason says what to fix. People subscribed to automation notifications are told either way.
Resuming
Resume continues from the step it stopped at, on top of the configuration as it is now. Before it resumes, the confirmation lists what changed in the plan's environments since it was paused, so you can see what you're resuming on top of. A plan never goes back and undoes a change made while it was paused.
Example: an incident during a rollout
- 1. 'Checkout rollout' has taken PRODUCTION to 25%; its next step is 50% on Tuesday.
- 2. Errors rise on Monday. An on-call engineer turns PRODUCTION off with one click.
- 3. The plan shows Suspended: Paused because sam@example.com turned PRODUCTION off. Tuesday's step does not run.
- 4. After the fix, the engineer turns PRODUCTION back on at 10%.
- 5. Someone presses Resume. The confirmation lists both changes.
- 6. The plan continues with its next step from the current configuration.
Configuration and Automation tabs
Every flag has two tabs under the same header: Configuration and Automation. Switching keeps the environment you were looking at. You can suspend and resume plans straight from the flag's Lifecycle & automation panel or from the environment's note; open the Automation tab to build or change a plan. Plan automation for PRODUCTION on an environment starts a new plan with that environment already chosen.
Flag Automations: flag lifecycles
A flag lifecycle is a derived summary of its configurations and retirement policy. It is different from an automation plan status such as Draft, Active, or Suspended. You normally change lifecycle by changing the flag configuration or its retirement plan, not by selecting a state manually.
| Lifecycle | What it means | How it changes |
|---|---|---|
| Created | No environment is currently serving the flag. | Enable a configured environment to move forward. |
| Active | At least one environment is enabled at 0% exposure. | Increase rollout above 0%, or disable all environments. |
| Rollout | At least one enabled environment is serving between 1% and 99%. | Move every enabled environment to 100% to become Fully released. |
| Fully released | Every enabled environment is serving at 100%. | A rollout change recalculates the state; an elapsed stale threshold can move it to Stale. |
| Stale | A fully released release flag has passed its configured stale threshold and should be reviewed. | Automation stops for stale flags. Archive it or create a replacement workflow after review. |
| Removal scheduled | A plan has a future archive date. The flag still evaluates normally until that date. | Use Cancel scheduled removal in the flag's Lifecycle & automation card to keep it and recalculate its state. |
| Archived | The flag is terminal and evaluations return the safe/off outcome. | Use the existing unarchive operation where permitted; archived automation cannot simply resume. |
Exactly what causes Removal scheduled?
Not default behaviorThis lifecycle is caused only when an automation has a future Schedule flag removal date (stored as archiveAt) and the plan is activated or reactivated. Ordinary rollout, promotion, enable, disable, expiration, and retirement-template stages do not schedule removal automatically.
- Plan-level scheduled date
- Schedule flag removal creates Removal scheduled immediately upon activation. It is flag-wide and remains effective even if the plan's ordinary stages finish first.
- Stage-level Archive flag action
- This waits for its stage trigger or approval and archives directly when it runs. By itself, it does not create the Removal scheduled state beforehand.
How to stop it: on the flag details page, select Cancel scheduled removal. This clears the date, cancels the active retirement automation that owns it, and recalculates the lifecycle from current environment configuration.
Technical requirements
Triggers
A stage uses exactly one trigger: a UTC instant displayed in the plan's IANA time zone, duration after the previous stage, total evaluations, unique-user count, lifecycle-state change, or manual approval. Consumption triggers name the measurement environment.
Actions
Enable, disable, set rollout from 0 through 100, promote a source configuration to targets, update audience targeting, set expiration, notify, or archive. Archive is terminal and must be the only action in its stage.
Audience and environment scope
Audience mode is everyone or context-based. Context mode supplies a field, accepted values, served variant, and fallback variant. Each action owns an explicit target list; promotion separately identifies its source and destinations.
Safety gates
A stage can require administrator approval, dependency-impact acknowledgement, and a telemetry deadline. A person's change to an environment the plan still controls suspends the plan as it is saved, so automation never overwrites newer work.
Gradual, environment, and scoped automation
Gradual rollout
Start at the first percentage in one environment, hold it for the configured soak time, then advance through the ordered steps. Deterministic evaluation keeps user assignment stable as exposure changes.
Environment journey
Promote from a known source into the next environment—even when no destination configuration exists yet—and gate sensitive destinations with approval. Optionally follow every promotion with its own gradual rollout.
Scoped audience
Combine an environment with context values. For example, release in Production to California users while other states receive the fallback variant.
Example: controlled production launch
- 1. Promote UAT configuration to Production.
- 2. Enable 10% at launch time.
- 3. Advance at 5,000 unique users.
- 4. Require approval before 50%.
- 5. Reach 100% after observation.
- 6. Notify on stale state and approve archive.
Guardrail metrics and rollback
Guardrails compare users receiving the rollout with users still held back. Error rate and latency are healthier when lower; conversion is healthier when higher. The regression limit is a percentage change, so values must be finite and within the allowed UI range. Sample size and confidence prevent decisions from being made on too little data.
With automatic rollback enabled, a confirmed regression returns the environment to its pre-rollout percentage. You can also roll back a running or suspended rollout manually whenever its current percentage differs from its starting percentage. Guardrails apply to Gradual rollout and to Environment rollout only when gradual release after promotion is enabled.
Execution model
The hosted AutomationTaskWorker checks due work on startup and then on a 30-second periodic cadence. One worker instance awaits an iteration before starting the next, so its own iterations do not overlap. Time triggers normally run within the next polling window; this is not exact-to-the-second scheduling.
Flag mutations, progress, lifecycle updates, and audit writes run as one retriable database transaction. Notifications dispatch after commit, so notification failure does not undo a completed change.
Validation and conflict rules
Protected environment versus pending approval
A Production badge or red policy dot means that the environment requires authorization; it does not necessarily mean approval is still pending. The stage status tells you whether that requirement has been satisfied.
No pre-approval is stored. Planned Events shows an Approve control to an administrator.
Authorization is already stored, commonly because an admin created or edited the plan. Planned Events shows Revoke approval instead, and protected stages may run unattended.
- Drafts: overlaps are allowed for experimentation and produce warnings; exact structural duplicates cannot be saved while an equivalent non-terminal plan exists. Cancelled and completed history does not block reuse.
- Activation and resume: conflicts are rechecked. Active plans lock action environments, promotion sources and targets, consumption measurement environments, and any flag-wide lifecycle resources they use.
- Suspended: retained but inactive. It does not reserve resources or conflict with a draft. Resume runs fresh validation and active-plan conflict checks.
- Terminal state protection: automation stops if a flag becomes Stale, Archived, or deleted and cannot reactivate or promote it. Active or suspended dependencies also protect referenced flags and environments from removal.
- Flag environments: ordinary actions target environments already configured for the flag. Environment rollout can additionally select eligible destinations with no flag configuration and create that configuration during promotion. Validation still enforces environment policy, approval, valid source configuration, and dependency safety. An environment used by an active or suspended plan can't be removed from the flag until the plan completes or is cancelled.
Plan lifecycle and controls
| Status | Meaning | Controls |
|---|---|---|
| Draft | Editable, not executing. | Edit, validate, activate, duplicate, delete. |
| Active | Worker may run ready stages. | Suspend, duplicate, cancel, delete; read-only editor. |
| Suspended | Stopped by a person, by pressing Suspend or changing an environment the plan controls. Retained and editable, but inactive; the reason says who changed what. | Edit, validate, resume, duplicate, cancel, delete. Suspend and resume also work from the flag page. |
| Errored | Stopped because a step could not run. Retained and editable, but inactive; the reason says what to fix. | Same as Suspended. |
| Completed | All stages finished. | Duplicate, import under another flag, or delete. |
| Cancelled | Stopped with no future execution. | Reactivate from stage one, duplicate, import, or delete. |
Existing plans appear newest-first as collapsed panels above the templates. Expanding selects one plan. Unsaved-change confirmation protects edits when switching, starting a scenario, cancelling, or deleting. Delete removes the editable payload and retains an audit tombstone.
Reuse and monitor automation
Import across flags
The automation planner can import a plan from another flag in any status. The picker identifies the plan status, owning flag, flag lifecycle, and creation date. Import always creates a new draft with fresh plan and stage IDs; it never links execution state back to the source.
After importing, review environment names, variants, dates, audiences, and safety gates. Validation uses the destination flag's current configuration.
Planned Events dashboard
Signed-in users can open Test → Planned Events to monitor every automation in the organization. Views separate upcoming, running, needs-attention, and done/stopped work. Search by plan, flag, environment, step, or action, then filter by execution state, approval state, or flag.
Editors and administrators can approve, suspend, resume, cancel, restart, or delete eligible plans from the dashboard. Reports can be exported as CSV, and each plan links to task details, its editor, and flag analytics.
| Planned Events field | What it tells you | Why it is useful |
|---|---|---|
| Next action | The next stage, its scheduled time, or the approval or error currently blocking it. | Answers “what happens next?” without opening the editor. |
| Elapsed | Time since activation or since the current rollout began. Drafts correctly show Not started. | Shows how long the release has actually been in motion. |
| Time left and pace | Estimated remaining duration and average duration of completed work. Estimates improve as stages finish. | Helps teams anticipate completion without treating the estimate as a deadline. |
| Next environments | The environments affected by the next incomplete stage. | Makes promotion and multi-environment impact visible before execution. |
| Rollout journey | Percentage checkpoints per environment, with current, completed, and waiting states. | Shows exposure progress at a glance. |
| Execution flow | Every stage, trigger, action, environment, and approval gate in order. | Explains the complete plan rather than only its current state. |
| Activity and past rollouts | Who started, edited, suspended, resumed, cancelled, completed, or rolled back work, plus prior rollout outcomes. | Open task details to inspect where a run stopped and its snapshot at that moment. |
Operational visibility and notifications
The flag's Automation tab shows active rollout progress, current serving percentage, journey checkpoints, elapsed time, next step, guardrail results, activity, and past rollouts. The Lifecycle & automation widget lists active and suspended plans with environments, next action or suspension reason, plus inline Suspend and Resume. Automation events also appear in the Change Log under the plan's user-facing name.
When automation changes a flag—enabling it, changing rollout, targeting, promotion, expiration, or archive—the same committed flag update path emits the audit event and notifies matching flag webhooks and real-time subscribers. Task details list the webhooks that hear about the plan. Notifications are sent after the database commit, so a delivery failure does not reverse a successful flag change.