Heroku FLAG_* Config Vars — Deprecation Tracking

Created: 2026-05-04 UTC Owner: operator / ops-agent Parent epic: #551 (in-console feature flag management) Runbook: docs/ops/feature-flags-runbook.md Design doc: docs/architecture/console-feature-flags.md sec 6 + 7 Follow-up cleanup issue: #1061

1. Background

FLAG_* Heroku config vars were the original flip mechanism for feature flags. The in-console flag management system (#551, #552, #553, #554) introduces a DB-backed override layer that supersedes them.

Resolution order (post-#552):

1. console_feature_flags DB row  — wins when FLAG_CONSOLE_FEATURE_FLAGS_DB=1 and row exists
2. FLAG_<UPPER_KEY> Heroku config var  — bootstrap fallback
3. feature_flags.yaml default           — final fallback

Once a flag is flipped via the console UI, a DB row is written for that (flag_key, env) pair. The Heroku env var is then dormant for that pair — it still exists on Heroku but has no effect. The env var remains a valid break-glass path only if FLAG_CONSOLE_FEATURE_FLAGS_DB=0 or if no DB row exists (see runbook §6).

Removal policy: remove a Heroku config var only after: 1. DB row confirmed present on both prod and staging. 2. >= 24h soak with DB row active and no regressions. 3. Audit log shows at least one console.flag.flip entry for each env.

2. Deprecation table

Status values: - active — env var is the live flip mechanism (DB layer not yet enabled or DB row absent) - dormant-after-flip — DB row exists; env var has no effect for this flag+env pair - can-remove — soaked >= 24h, both envs confirmed, ready for heroku config:unset - removed — env var deleted from Heroku

Flags not listed here are managed via YAML default only and have no Heroku config var.

Console flags

Non-console flags (Raptor + Antlers)

3. Heroku config var removal — follow-up issue #1061

Issue #1061 tracks the actual heroku config:unset step. That issue is intentionally separate from this doc so the unset step is never automated silently — operators must confirm via the audit log that the DB row is live before removing the env var safety net.

Do not remove any Heroku config var until: 1. The DB row for that (flag_key, env) pair is confirmed present on both prod and staging. 2. The flag has soaked for >= 24h with no regressions. 3. The audit log shows at least one console.flag.flip entry per env. 4. The status in this table has been updated to can-remove.

4. Instructions for updating this table

When an operator flips a flag via the console UI for the first time on a given env:

1. Confirm the DB row exists: sql SELECT flag_key, env, value, updated_at FROM console_feature_flags WHERE flag_key = '<key>' AND env = '<env>';
2. Update the Status column in this table to dormant-after-flip.
3. After >= 24h soak with no regressions: update to can-remove.
4. After running heroku config:unset on both apps: update to removed and record the date.

5. Removal timing

There is no hard deadline for removing dormant Heroku config vars. The recommended window is within 30 days of GA sign-off for any flag where the DB row is confirmed live on both envs.

The FLAG_CONSOLE_FLAG_MGMT env var (the rollout gate for the flag management feature itself) is the only var with a firm removal target: it should be removed as part of GA sign-off for #551, since the feature self-gate is not needed post-GA. See runbook §9 (GA sign-off checklist).