Retiring feature flags after launch

Feature flags are what make trunk-based development work: unfinished features merge daily and stay dark until ready. Every one of those flags is also a branch in the code — two paths, two behaviours, twice the testing — and once the feature is launched, the old path is dead weight. Teams that adopt flags without a retirement habit end up with hundreds of them, some fully on for years, some guarding code nobody remembers, and an occasional outage when someone toggles a flag everyone assumed was obsolete. Retiring flags is ordinary engineering work, but it needs structure: every flag has an owner and an expiry from the day it is created, stale flags are found mechanically, and removal happens in safe steps. This page sets that up, within trunk-based development setup.

When to use this approach

  • Your codebase uses feature flags for unfinished or gradually rolled-out work.
  • Nobody can say how many flags exist or which ones are still needed.
  • Flags that have been fully on for months still have both code paths.
  • You are starting to use flags and want to avoid accumulating them, as in feature flags vs feature branches for unfinished work.

Step 1 — Register every flag with an owner and an expiry

Keep a registry of flags in the repository: name, owner, purpose, creation date and expected removal date. Creating a flag means adding an entry in the same pull request.

# flags.yml — every flag the code may read
- name: export-scheduling
  owner: "@acme/data-platform"
  purpose: Gate the per-account export scheduler during rollout
  created: 2026-09-14
  remove_by: 2026-11-30
  type: release            # release | experiment | ops | permission
- name: payments-new-provider
  owner: "@acme/billing"
  purpose: Branch-by-abstraction switch to the new payment provider
  created: 2026-08-02
  remove_by: 2026-10-31
  type: release
Kinds of flag and their lifetimesRelease flags hide unfinished work and should be removed within weeks of launch. Experiment flags run an A/B test and go when it concludes. Ops flags are kill switches that may stay long-term on purpose. Permission flags gate features by plan or customer and are product configuration rather than temporary code.Releaseweeksremove after launchExperimentweeks to monthsremove at conclusionOpslong-lived kill switchby designPermissionproduct confignot temporaryonly the first two kinds should have a remove_by date — and they are most flags

A CI check keeps the registry and the code in sync: every flag referenced in code must be registered, and every registered flag must still be referenced or be removed from the registry.

git grep -hoE 'flags\.enabled\("[a-z0-9-]+"' -- 'src/**' | sed 's/.*("//; s/"//' | sort -u > /tmp/flags-used
yq -r '.[].name' flags.yml | sort -u > /tmp/flags-registered
comm -23 /tmp/flags-used /tmp/flags-registered | sed 's/^/unregistered: /'
comm -13 /tmp/flags-used /tmp/flags-registered | sed 's/^/no longer used: /'

Step 2 — Find stale flags mechanically

A flag is a removal candidate when its expiry has passed, or when it has been fully on (or off) in every environment for some weeks. List both kinds weekly.

today=$(date +%F)
yq -r '.[] | select(.type=="release" or .type=="experiment") | select(.remove_by < "'"$today"'") |
       "\(.remove_by)  \(.name)  \(.owner)"' flags.yml

Git history adds another signal: when did the flag’s code paths last change? A flag whose guarded code has not been touched in months is usually settled.

git log -1 --format='%cs' -S'"export-scheduling"' -- src/
Flags by age in an unmanaged codebaseAn illustrative codebase before introducing a flag registry. A handful of flags are recent and still rolling out, but most are older than six months, and many guard features that have been fully on for a year.flags by age (illustrative)< 1 month91–6 months216–12 months34> 1 year58the right-hand bars are almost all removable — and each one doubles some code path

Step 3 — Remove flags in safe steps

Removing a flag is a code change with production consequences: it hard-codes one path. Do it in steps that can each be undone.

  1. Confirm the flag’s value is the same everywhere and has been for a while.
  2. Remove the flag check in code, keeping the winning path — one pull request.
  3. Deploy, and only then remove the flag from the flag service and the registry.
git switch -c chore/remove-flag-export-scheduling origin/main
git grep -n '"export-scheduling"' -- src/ tests/
# edit each site: keep the enabled branch, delete the disabled branch and its tests
git commit -am "chore: remove export-scheduling flag (launched 2026-10-12)"

Removing the code before the flag-service entry means a deploy rollback still finds the flag defined and behaves correctly.

⚠️ SAFETY WARNING: Removing a flag check that was not truly at the same value everywhere changes behaviour for some customers — for example, a flag fully on in production but off for one enterprise tenant. Check per-environment and per-segment values in the flag service before removal. If behaviour changed unexpectedly, revert the removal commit; the flag still exists in the service until step 3 completes.

Step 4 — Make retirement part of the launch

The easiest time to remove a flag is right after launch, while its author remembers the code. Add “remove flag” as a final task in the same ticket that launches the feature, scheduled a couple of weeks after full rollout.

# Open a removal pull request automatically for flags past their date
yq -r '.[] | select(.remove_by < "'"$(date +%F)"'") | .name' flags.yml | while read -r f; do
  gh issue create --title "Remove flag $f" --label flag-cleanup \
    --body "Flag \`$f\` passed its remove_by date. Owner: $(yq -r ".[] | select(.name==\"$f\") | .owner" flags.yml)"
done

Step 5 — Watch the total

Track the number of release and experiment flags over time. A steady or falling count means retirement keeps pace with creation; a rising one means the habit has slipped.

A flag's life from creation to removalA flag is created with a registry entry, owner and removal date. The feature rolls out behind it and reaches everyone. Two weeks later a cleanup task removes the check from code, the change deploys, and the flag is deleted from the service and the registry.Createregistry + ownerRoll outpilot → everyoneSettletwo weeks fully onRemove codekeep winning pathDelete flagservice + registryremoval is scheduled at creation, not discovered a year later

Validation checklist

Frequently Asked Questions

What about flags that should live forever?

Kill switches and permission gates are legitimate long-lived flags. Register them with type ops or permission and no removal date, so they are distinguishable from forgotten release flags.

How do we remove a flag that guards complicated code?

The same way as any refactor: in small steps, with tests on the winning path first. If the code is tangled, removing the flag is often a good moment to simplify it, in a follow-up pull request.

Should tests cover both flag states?

While the flag is live, yes. When the flag is removed, delete the tests for the losing path along with the code.