Skip to content
FlagSwiftDocs

Flag lifecycle and cleanup

Every flag is temporary unless you say otherwise. FlagSwift tracks who owns each one, how old it is, and whether it is safe to remove, so flags do not pile up as dead code.

What is tracked#

Per flag
FieldTypeDescription
OwneremailWho looks after the flag. Defaults to whoever created it; change it on the flag's Lifecycle tab.
CreateddateWhen the flag was created.
Last modifieddateThe latest change to the flag or any of its environments.
Last evaluateddateThe latest server evaluation on record. Only as far back as metrics are kept (30 days). When none is inside that history it reads as unknown, not as never.
Expected removaldateWhen the team plans to take the flag out of code. Past this date the flag shows as removal due.
ExpirationdateAfter this date the flag shows as expired. Nothing is switched off for you.
PermanentbooleanFor flags meant to stay, such as kill switches or entitlements. They are never listed as stale and take no dates.

Status, last modified and the removal advice are worked out each time you look, not stored, so the same flag can turn stale on its own as time passes.

Status#

A flag has one status. When several apply, the first of these wins:

  • Archived: not served; can be restored or deleted.
  • Expired: the expiration date has passed.
  • Removal due: the expected removal date has passed.
  • Expiring soon: the expiration date is within 14 days.
  • Permanent: marked to stay.
  • Stale: see below.
  • Removal planned: a removal date is set and still ahead.
  • Active: none of the above.

Stale flag detection#

A flag older than 14 days is stale when any of these holds:

  • It is off in every environment and has not been changed for 14 days.
  • It is on for everyone (100%, no active emergency stop) in every environment and unchanged for 14 days. The code only has dead branching left.
  • Nothing has evaluated it for 14 days, judged from the evaluation history that exists.

Evaluation history has limits

A flag evaluated only inside an SDK that does not report evaluations, or only before the history begins, can look unused. The Lifecycle page says where the history starts. Treat “not evaluated” as a prompt to check, and use code references to be sure.

Removal advice#

Each flag carries a one-sentence verdict, for example Flag has been OFF for 120 days. Potentially safe to remove. The verdict is one of four:

  • Safe to remove: it has been off, fully on, or unused for 30 days or more, and a code scan found no references.
  • Potentially safe: the same, but no repository has reported code references yet, so use in code is unknown.
  • Not safe: code still uses the flag, or another flag lists it as a prerequisite. This always wins, however long the flag has been quiet.
  • Not ready: still changing, still being rolled out, permanent, or quiet for fewer than 30 days.

Cleanup#

The Lifecycle page lists a project's flags with the ones that need attention first. Filter by owner, status or search, select flags, and archive up to 50 at once. A flag that another flag needs as a prerequisite is skipped and reported.

Removing a flag is always two steps. Archive it, which stops it being served but keeps everything so you can restore it. Then delete it from the Advanced tab, which is permanent. If code still references the flag, deleting asks for a separate confirmation and lists the files, because that code will fall back to its default value.

Code references#

The scanner finds where your code reads each flag and reports it, so a flag's Lifecycle tab can say, for example:

text
checkout-v2
  Used in:
    src/checkout/payment.ts:42
    src/components/Checkout.tsx:18
    src/api/payment.ts:91

It is a single file with no dependencies, tools/flagswift-scan.mjs in the FlagSwift Enterprise repository, and needs Node 18 or later. Create an admin key with the code_references:write scope for the project and run it in CI on your main branch:

.github/workflows/flagswift-scan.yml
name: FlagSwift code references
on:
  push:
    branches: [main]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: node tools/flagswift-scan.mjs
        env:
          FLAGSWIFT_URL: https://flags.example.com
          FLAGSWIFT_API_KEY: ${{ secrets.FLAGSWIFT_ADMIN_KEY }}
Options
OptionTypeDescription
--url, --keystringThe FlagSwift address and admin key, or set FLAGSWIFT_URL and FLAGSWIFT_API_KEY.
--repositorystringThe name shown in the console, or set FLAGSWIFT_REPOSITORY. Defaults to the git origin name, then the folder name.
--dirpathThe folder to scan. Defaults to the current folder.
--flagsfileFlag keys, one per line, instead of fetching them from FlagSwift.
--looseflagCount a key anywhere in code, not only inside quotes. More matches, more false positives.
--ignorenameAn extra folder or file name to skip. Repeatable.
--dry-runflagPrint what was found and send nothing.
--jsonflagPrint the result as JSON.
--helpflagPrint the options and exit.
  • A reference is the flag key written as a string, such as isEnabled("checkout-v2"). Keys assembled at runtime cannot be found, so mark those flags permanent or keep them out of cleanup.
  • Each scan replaces what that repository reported before, so a flag removed from code disappears from the list on the next scan. Other repositories are untouched.
  • Folders such as node_modules, dist and .git, lock files, binary files and files over 1 MB are skipped. Up to 100 locations are kept per flag per repository.
  • Until a repository has reported, removal advice says “potentially” safe, because use in code is unknown. After the first scan it can say safe.