Find and remove stale flags
Find the flags nobody needs any more, check that your code no longer reads them, and archive them before they become dead branches.
- Time
- About 8 min
- Who can do it
- Developer, Release manager or Admin to archive. Admin to delete for good.
- Where
- Flag lifecycle in the console, then a flag's Lifecycle and Advanced tabs
- You finish with
- Finished flags archived, and the code that read them already removed
What and why#
What a stale flag is#
A flag is stale when it has stopped doing work: it has been off everywhere, fully on for everyone, or unread for at least 14 days. Its code path is now dead weight, and each one makes the next change harder to reason about.
How cleanup works here#
The Flag lifecycle list works out a status and a removal verdict for every flag from its configuration, its recent evaluations, a scan of your code and the flags that depend on it. You remove the flag from code first, then archive it, and only delete it for good when you are sure.
Why archive before deleting#
Archiving hides the flag and stops serving it, but keeps its configuration and history, and you can restore it at any time. Deleting is permanent.
Before you start#
- Run the code scanner at least once, so removal advice can tell whether code still uses a flag. See Link flags to your code. Without it, the best verdict is Potentially safe.
- Permission to archive flags (
flags.archive): Developers, Release managers and Admins. Deleting for good (flags.delete) is for Admins only. - Evaluation history, which is kept for 30 days by default. A flag no SDK evaluated in that window looks unused.
Walk through it#
Open the list
Open Flag lifecycle, choose the Project and set Show to Needs attention. That covers stale, expiring, expired and removal due flags. Narrow it with Owner or the search box. The note under the tiles says where evaluation history begins and whether any repository has reported code references.
Read the removal verdict
Each row has a verdict and a one-sentence reason, such as Flag has been OFF for 120 days. Potentially safe to remove.
Needs attention in the Web app project. The tiles count flags; the note under them says whether code has been scanned. Removal verdicts Verdict Description Safe to remove Off, fully on or unused for 30 days or more, and a scan found no references. Potentially safe to remove The same, but no repository has reported yet, so use in code is unknown. Not safe to remove Code still uses it, or another flag lists it as a prerequisite. This always wins. Not ready to remove Still changing or rolling out, marked permanent, or off, fully on or unused for fewer than 30 days. You should see. An archived flag with no references reads “Archived and no code references were found. Safe to delete.”Check the owner and the code
Open a flag from its name and go to its Lifecycle tab. Code references lists each repository and the files and lines that read the flag. For a flag with an owner, ask them before you remove it. Remove the flag from code first, deploy, and let the next scan run so the references clear.
Archive
Tick the flags and choose Archive selected, or use Archive on one row, then confirm. You can archive up to 50 at once, and each flag is attempted on its own, in order. Archived flags stop being served, so SDKs fall back to their default value. A flag that is another flag's prerequisite is skipped and reported, and the rest still archive.
Selecting rows reveals the bar with Archive selected, and the confirmation names how many flags are involved. You should see. The archived flags leave the list and appear under Show: Archived.Delete when you are sure
Admins only. Open the archived flag, go to the Advanced tab and choose Delete permanently. If code still uses the flag, the dialog lists the places (up to 20) and you must switch on Delete it anyway, because that code will fall back to its default. Then type the flag key to confirm. To bring a flag back instead, choose Restore flag on the same tab.
Delete permanently for an archived flag that code still uses. The confirm button stays disabled until Delete it anyway is on and the key is typed exactly.
Unused is not proof
checkout-${name}, cannot be found by the scanner. Mark those flags permanent or keep them out of cleanup.Do it with the API#
List what needs attention, then archive in bulk
Both are Dashboard API calls that act as the signed-in person. Each result says whether that flag was archived, so one refusal does not stop the others. The list call also returns counts for every filter, the project's codeScan state and collectingSince. See the Lifecycle API.
# Flags that need attention in a project (flags.read, session cookie)
curl -s "https://flags.example.com/api/lifecycle?projectId=PROJECT_ID&filter=attention&limit=25" -b jar.txt
# Archive several flags at once (flags.archive). Up to 50 ids.
curl -X POST "https://flags.example.com/api/lifecycle/archive" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"ids":["FLAG_ID_1","FLAG_ID_2","FLAG_ID_3"]}'{
"status": "success",
"message": "Some flags could not be archived",
"data": {
"results": [
{ "id": "FLAG_ID_1", "ok": true },
{ "id": "FLAG_ID_2", "ok": true },
{ "id": "FLAG_ID_3", "ok": false, "error": "Cannot archive \"Payments v2\": it is a prerequisite of Express pay (production). Remove the dependency first." }
],
"archived": 2,
"failed": 1
}
}What to check#
- The archived flags move to the Archived filter.
- Your applications still run, and the Errors page shows no new unknown flag keys.
- Anything that was skipped has a prerequisite to remove first.
Good to know#
Do it on a routine
Why does a flag I use show as stale?
Can I archive from the flag instead of the list?
What happens to apps that still read an archived flag?
false). Nothing throws, but behaviour can change, which is why you remove the code first.Can I undo an archive?
If something goes wrong#
Some flags could not be archived
Why: Another flag lists it as a prerequisite (FLAG_IS_PREREQUISITE), or the project is archived. The result names the flags that depend on it.
Fix: Open the flag named in the message, remove the prerequisite on its Targeting & rollout tab, then archive again.
Archive up to 50 flags at a time
Why: A bulk request carried more than 50 ids.
Fix: Archive in batches of 50 or fewer.
Every flag says Potentially safe, never Safe
Why: No repository has reported code references for this project yet.
Fix: Run the scanner from CI. The advice changes to Safe once a repository has reported and found no references.
This flag is still used in N places in code (HAS_CODE_REFERENCES)
Why: A delete was refused because the last scan found references.
Fix: Remove the code and let the next scan run, or confirm Delete it anyway.
A flag I know is unused is not in Needs attention
Why: It is under 14 days old, marked permanent, or evaluated recently by an SDK.
Fix: Open its Lifecycle tab and read the findings. Set an expected removal date to make it surface on a date you choose.