Skip to content
FlagSwiftDocs

Give every flag an owner and an end date

Say who looks after each flag and when it should go, so finished flags get noticed instead of piling up in your code.

Time
About 8 min
Who can do it
Anyone who can edit the flag: Product manager, Developer, Release manager or Admin
Where
A flag's Lifecycle tab, and the Flag lifecycle list
You finish with
An owner and a removal plan on every flag, and a list that shows what needs attention

What and why#

What it is#

Every flag can carry an owner (who answers for it), an expected removal date (when the team plans to take it out of code), an expiration date (when it stops being valid) and a permanent switch for flags that are meant to stay. FlagSwift combines these with how the flag is configured and used into one status.

Why bother#

Release flags are meant to be temporary. Without an owner and a date, a finished flag leaves a dead branch in your code and nobody knows whether it is safe to remove. With them, the Flag lifecycle list tells you what to look at this week.

Temporary or permanent#

  • Temporary: release flags, experiments, migrations. Give them a removal date.
  • Permanent: kill switches, operational toggles and entitlements. They take no dates and are never listed as stale.

Before you start#

  • Permission to edit the flag (flags.update). An archived flag is read-only until you restore it.
  • A decision for each flag: temporary or permanent. When unsure, treat it as temporary and set a date a few sprints out.

Walk through it#

  1. Open the Lifecycle tab

    Open Flags, choose the flag and open the Lifecycle tab. At the top, Removal shows a verdict and a one-sentence reason. Below, the summary shows Status, Owner, Created, Last modified, Last evaluated, Expected removal and Expires.

    The top of the Lifecycle tab: the removal verdict, then the summary list.
    You should see. Last evaluated reads a time, “No evaluation history yet” or “Not in the history kept”. The last two mean unknown, not never.
  2. Set an owner

    Under Ownership and dates, enter the Owner as an email address (up to 254 characters). It defaults to whoever created the flag, and the field shows that address as its placeholder. Clearing the field falls back to the creator. The address is stored in lower case.

  3. Choose permanent or temporary

    Switch on Permanent flag for a flag meant to stay. A permanent flag takes no dates, so the date fields disappear and any saved dates are cleared when you save. For a temporary flag, set an Expected removal date (when the team plans to remove the flag from code) and an optional Expiration date (after this date the flag is shown as expired). Then choose Save, or Discard to undo.

    Ownership and dates. With Permanent flag on, the two date fields are hidden.

    Dates are saved as the start of that day in UTC, so a date can show as the day before in time zones behind UTC. The Save button is enabled only after a change.

    You should see. The summary updates and the change appears in the audit log as flag.updated.
  4. Watch it on the list

    Open Flag lifecycle, choose a project and use Show to pick All active flags, Needs attention, Stale, Expiring soon, Expired, Removal due, Permanent or Archived. Filter by Owner to see one person's flags. The tiles at the top count Needs attention, Stale, Expiring or expired, and Removal due. Flags that need attention are listed first.

    The Flag lifecycle list. Each row shows status, owner, last change, last evaluation, dates and a cleanup verdict.

Dates are reminders

Nothing is switched off when a date passes. The flag shows as expired or removal due, and it keeps serving until someone acts.

How status is worked out#

Status is calculated each time you look, not stored, so the same flag can be stale tomorrow. When several apply, the first of these wins:

Statuses, in the order they are checked
StatusDescription
ArchivedThe flag is archived. Not served; it can be restored or deleted.
ExpiredThe expiration date has passed.
Removal dueThe expected removal date has passed.
Expiring soonThe expiration date is within 14 days.
PermanentMarked permanent. Never stale.
StaleAt least 14 days old, and either off everywhere, fully on everywhere (100%, no kill switch) and unchanged for 14 days, or not evaluated for 14 days.
Removal plannedA removal date is set and still ahead.
ActiveIn use, with nothing to clean up yet.

Last evaluated only reaches back as far as metrics are kept (30 days by default), so an unknown value is not the same as never. A flag is called potentially or fully safe to remove only after 30 days of being off, fully on or unused. See Flag lifecycle and cleanup for the full rules.

Do it with the API#

Set the lifecycle fields and read the status

The lifecycle response is a plain object (no status envelope). Send null to clear the owner or either date. Setting permanent: true while a date is still set is refused with PERMANENT_WITH_DATES, so send both dates as null in the same call. GET /api/lifecycle?projectId=...&filter=attention lists a whole project. See the Lifecycle API.

Request
# Dashboard API: session cookie, permission flags.update
curl -X PATCH "https://flags.example.com/api/flags/FLAG_ID" \
  -b jar.txt -H "Content-Type: application/json" \
  -d '{"owner":"dana@example.com","expectedRemovalAt":"2026-12-15","expiresAt":null,"permanent":false}'

# Read one flag's lifecycle (flags.read)
curl -s "https://flags.example.com/api/flags/FLAG_ID/lifecycle" -b jar.txt
Lifecycle response
{
  "status": "scheduled_removal",
  "owner": "dana@example.com",
  "permanent": false,
  "createdAt": "2026-08-04T09:12:00.000Z",
  "lastModifiedAt": "2026-09-20T14:00:00.000Z",
  "lastEvaluatedAt": "2026-10-03T08:55:00.000Z",
  "evaluationsTracked": true,
  "expectedRemovalAt": "2026-12-15T00:00:00.000Z",
  "expiresAt": null,
  "archivedAt": null,
  "ageDays": 60,
  "state": "mixed",
  "stateDays": 0,
  "findings": [],
  "removal": { "verdict": "not_ready", "message": "Still in active use. Nothing suggests it can be removed yet." },
  "codeReferences": { "count": 0, "scanned": false }
}

What to check#

  • The Lifecycle tab shows the owner and dates you saved.
  • The flag appears when you filter the Flag lifecycle list by that owner.
  • A date in the past changes the status to Expired or Removal due.

Good to know#

Nobody is notified today

Owners are plain email addresses and nothing is sent when a date passes. Check the Flag lifecycle list on a routine, for example at the start of each sprint, and filter by yourself under Owner.
Can the owner be someone who is not a member?
Yes. The owner is only an email address and is not checked against your members.
Should the removal date come before the expiration date?
Usually the other way round: cleanup lags expiry, so a removal date after the expiration date is allowed.
Why is my flag stale when it is in use?
Stale looks at the configuration as well as use. A flag that is on for everyone in every environment and unchanged for 14 days is stale even if it is evaluated all day: it is a finished rollout waiting to be removed. Mark it permanent if it is meant to stay.
How do I keep a kill switch out of the cleanup list?
Switch on Permanent flag. It is never listed as stale and takes no dates.

If something goes wrong#

Owner must be an email address

Why: The owner field accepts only an email address of up to 254 characters.

Fix: Enter a full address such as dana@example.com, or clear the field to fall back to the creator.

A permanent flag cannot have an expiration or expected removal date (PERMANENT_WITH_DATES)

Why: The request left a date set while marking the flag permanent.

Fix: Send expectedRemovalAt and expiresAt as null in the same request. The console clears them for you.

Expected removal date must be a valid date

Why: The date could not be read.

Fix: Use an ISO date such as 2026-12-15.

Last evaluated says Not in the history kept

Why: No evaluation is on record inside the metrics history (30 days by default).

Fix: Treat it as unknown. A flag read by an SDK that does not report evaluations can look unused.

The Save button is disabled

Why: Nothing has changed, or the flag is archived and therefore read-only.

Fix: Edit a field, or restore the flag from its Advanced tab first.