Rulestead keeps one flag identity with environment-specific authored behavior.
Operators should think in terms of the same flag moving through dev,
staging, and prod, not three unrelated flags.
Canonical Environment Selector
In the mounted admin package, the URL query parameter env is the canonical
environment selector:
/admin/flags?env=dev/admin/flags/checkout_v2?env=staging/admin/flags/checkout_v2/rollouts?env=prod
If env is missing, the package may fall back to the host-provided
"rulestead_admin_last_env" session value. The host also provides the available
picker options through "rulestead_admin_environments".
Why The Query Param Matters
Treat ?env= as part of the operator contract because it keeps workflows:
- bookmarkable
- shareable across operators
- explicit in incident notes and rollout reviews
That is a better seam than reaching into internal admin state.
Recommended Promotion Pattern
Use the same flag across environments, but advance it deliberately:
- author and verify in
dev - publish and rehearse in
staging - promote and monitor in
prod
Keep the authored intent recognizable across environments even when the exact
rule values differ. For example, the same rollout rule may be 100% in staging
but 10% in prod while the rollout is still live.
Environment-Specific Work
The environment selector matters for every operator workflow:
- list and detail views show one environment's current truth at a time
- rules drafts and publish actions apply in the selected environment
- explain and simulation should always name the environment explicitly
- kill switch actions are per-flag and per-environment
- timeline review should be read in the environment where the change happened
This is how the package preserves a single flag identity without losing operational clarity.
Runtime Perspective
Outside the admin UI, keyed runtime APIs also require the environment:
Rulestead.Runtime.evaluate(environment_key, flag_key, context)Rulestead.Runtime.enabled?(environment_key, flag_key, context)Rulestead.Runtime.get_value(environment_key, flag_key, context, default)Rulestead.Runtime.get_variant(environment_key, flag_key, context)Rulestead.Runtime.explain(environment_key, flag_key, context)
That mirrors the operator flow: environment is always explicit.
Keep Secrets And Policies Out Of The Guide
Multi-environment support does not imply built-in auth or tenant policy. The host app still owns:
- which environments appear in the picker
- who may read or change each environment
- how environment names map to deployment or compliance boundaries
Rulestead documents the mount seam and environment convention, then leaves those authorization choices to the host policy module.
Compare And Promotion Dependency Findings
Compare and promotion surfaces show audience dependency findings with
explicit environment and tenant scope on links (?env=, tenant_key, or
equivalent). Same-name audiences across environments or tenants are not
assumed equivalent — the host owns tenant catalog and authorization; Rulestead
carries scope on payloads only.
Promotion and manifest import fail closed on missing or incompatible reusable targeting assets. Compare and promotion dependency findings are read-only — operators cannot Apply or Publish from compare surfaces.
When reviewing cross-environment drift, treat dependency findings as scoped signals requiring explicit env/tenant context, not as global truth.
Protected environments and blast radius thresholds
Protected environments (commonly production) trigger blast-radius threshold evaluation on audience mutations. Routing depends on the threshold verdict:
- Below threshold — direct apply remains eligible after fresh preview confirm
- Above threshold — mutations must route through change request review and execute
Rulestead fails closed when the preview fingerprint is stale, dependency truth is unresolved, or required threshold inputs are missing. Operators should not assume silent direct apply in those states.
Impact previews use preview basis only (authored references and explicit samples). They do not claim affected-user counts or observability-backed population totals — the host owns metrics and identity boundaries.