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#
| Field | Type | Description |
|---|---|---|
| Owner | Who looks after the flag. Defaults to whoever created it; change it on the flag's Lifecycle tab. | |
| Created | date | When the flag was created. |
| Last modified | date | The latest change to the flag or any of its environments. |
| Last evaluated | date | The 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 removal | date | When the team plans to take the flag out of code. Past this date the flag shows as removal due. |
| Expiration | date | After this date the flag shows as expired. Nothing is switched off for you. |
| Permanent | boolean | For 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
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:
checkout-v2
Used in:
src/checkout/payment.ts:42
src/components/Checkout.tsx:18
src/api/payment.ts:91It 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:
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 }}| Option | Type | Description |
|---|---|---|
| --url, --key | string | The FlagSwift address and admin key, or set FLAGSWIFT_URL and FLAGSWIFT_API_KEY. |
| --repository | string | The name shown in the console, or set FLAGSWIFT_REPOSITORY. Defaults to the git origin name, then the folder name. |
| --dir | path | The folder to scan. Defaults to the current folder. |
| --flags | file | Flag keys, one per line, instead of fetching them from FlagSwift. |
| --loose | flag | Count a key anywhere in code, not only inside quotes. More matches, more false positives. |
| --ignore | name | An extra folder or file name to skip. Repeatable. |
| --dry-run | flag | Print what was found and send nothing. |
| --json | flag | Print the result as JSON. |
| --help | flag | Print 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,distand.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.