Link flags to your code with code references
Scan a repository from CI so each flag shows the files and lines that read it, and removal advice can say when a flag is safe to delete.
- Time
- About 10 min
- Who can do it
- Admin to create the key. Anyone who can view flags reads the results.
- Where
- Your CI, then a flag's Lifecycle tab and the Flag lifecycle list
- You finish with
- Every flag shows where it is used, and removal advice is based on real data
What and why#
What code references are#
A code reference is a place in your repository where a flag key appears as a string, for example isEnabled("checkout-v2") in src/checkout/payment.ts line 42. A scanner finds them and reports them to FlagSwift, which shows them on the flag.
Why it matters#
- Before you archive or delete a flag, you can see exactly which files still read it.
- Removal advice can move from “potentially safe” to “safe”, because it can tell “no code uses this” apart from “nobody has looked”.
- A flag that code still uses is marked Not safe to remove, whatever its state.
How it works#
The scanner runs in CI on your main branch. It asks FlagSwift for the project's flag keys, searches the repository for them, and sends back the locations. Each scan replaces what that repository reported before, so a flag you removed from code disappears on the next run, and other repositories are untouched.
Before you start#
- Node 18 or later where the scan runs, and the scanner file
tools/flagswift-scan.mjsfrom the FlagSwift repository. It has no dependencies. - An admin API key for the project, with the
code_references:writescope. Admin keys get that scope by default. Open API keys to create it (Admins only), and keep it in your CI secrets. A key can never hold more than its creator, so the creator needsflags.update. - Your code reads flags with the key written as a string, such as
isEnabled("checkout-v2"). - Your server address. The key belongs to one project, so run one scan per project.
Walk through it#
Create the scanner key
In API Keys, choose New API Key, set Type to Admin, pick the Project you want to scan and choose Create Key. The key belongs to that project, so create one per project. Copy the key into your CI secrets from the dialog.
The Create API Key dialog for the scanner. Leave Environment on All environments; the scanner does not read one environment. Try a dry run
From the repository folder, print what would be found and send nothing.
bash FLAGSWIFT_URL=https://flags.example.com \ FLAGSWIFT_API_KEY=$KEY \ node tools/flagswift-scan.mjs --dry-runThe scanner fetches the project's flag keys with your key, so it only looks for real flags. It prints each flag with its locations and ends with a summary line.
Example output checkout-v2 Used in: src/checkout/payment.ts:42 src/checkout/summary.tsx:17 new-dashboard Used in: src/pages/home.tsx:8 2 of 14 flags are used in acme/web; 12 are not referenced. Dry run: nothing was sent.You should see. The flags you expect are listed with the right paths and lines. If you have no network, pass--flags keys.txt(one key per line) together with--dry-runto try it offline.Run it in CI
Run the same command, without
--dry-run, on your main branch, with the key in a secret. Use--repositoryto set the name shown in the console; by default it is the git origin name, then the folder name..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 }}You should see. The job ends with Reported 2 flags and 3 locations to FlagSwift, and adds ; N flags no longer referenced were cleared when something was removed from code.Read the result
Open Flags, choose a flag and open the Lifecycle tab. Code references lists each repository with its branch and the first 7 characters of the commit, and every file and line. Before any repository has reported, it says No repository has reported yet instead of showing zero. After a scan that found nothing it says No code references found with the time of the scan.
Code references on the Lifecycle tab after one scan of acme/web. Use it for cleanup
The Flag lifecycle list shows a reference count on each flag, and removal advice switches from “potentially” safe to safe once a repository has reported. A flag with references is Not safe to remove until they are gone.
What the scanner finds and its limits#
| Option | Description |
|---|---|
| --url, --key | The server address and the admin key. Or set FLAGSWIFT_URL and FLAGSWIFT_API_KEY. |
| --repository | The name shown in the console (FLAGSWIFT_REPOSITORY), up to 200 characters. |
| --dir | The folder to scan. Defaults to the current folder. |
| --flags | A file of flag keys, one per line, instead of fetching them. |
| --loose | Count a key anywhere in code, not only inside quotes. Finds more, and adds false matches. |
| --ignore | An extra folder or file name to skip. Repeat it for several. |
| --dry-run, --json | Print without sending, or print the report as JSON. |
- A reference is the flag key inside quotes (single, double or backtick). Keys built at runtime, like
`checkout-${name}`, cannot be found. - Folders such as
node_modules,dist,buildand.git, lock files, binary files, lines over 5,000 characters and files over 1 MB are skipped. - Up to 100 locations are kept per flag per repository (the true count is still reported), 2,000 flags per scan and 50 repositories per project.
Other languages and tools
POST /api/v1/code-references and the same admin key.Do it with the API#
Report references from your own tooling
The first call returns { "flags": [{ "key": "checkout-v2", "archived": false }] }, archived flags included and marked, and needs a server or admin key. The report needs an admin key with code_references:write, and its project is the key's own. unknownKeys lists reported keys that match no flag. Repository names, flag keys and paths are limited to 200, 200 and 500 characters, and a report with more than 2,000 flags is refused. To read the result back, a signed-in person can call GET /api/flags/FLAG_ID/code-references with a session cookie. See the Evaluation API and Lifecycle API.
# Evaluation API: authenticates with the admin key as a bearer token (no cookie)
curl -s "https://flags.example.com/api/v1/code-references/flags" \
-H "Authorization: Bearer $FLAGSWIFT_ADMIN_KEY"
curl -s -X POST "https://flags.example.com/api/v1/code-references" \
-H "Authorization: Bearer $FLAGSWIFT_ADMIN_KEY" -H "Content-Type: application/json" \
-d '{
"repository": "acme/web",
"branch": "main",
"commit": "9f2c1ab4e7d3",
"flags": [
{ "flagKey": "checkout-v2", "locations": [{ "path": "src/checkout/payment.ts", "line": 42 }] }
]
}'{
"repository": "acme/web",
"flags": 1,
"locations": 1,
"cleared": 0,
"unknownKeys": []
}What to check#
- The dry run lists the flags you expect, with the right paths and lines.
- A flag you know is used shows locations on its Lifecycle tab.
- Deleting an archived flag that code still uses lists the files and asks for a separate confirmation.
Good to know#
A scan only reflects the branch you scanned
Does scanning send my source code to FlagSwift?
I have several repositories. How do I scan them?
--repository name. Each repository's report is independent, and one project accepts up to 50.Why does a flag still show references after I removed it?
Can a server key run the scanner?
code_references:write.If something goes wrong#
Set FLAGSWIFT_URL and FLAGSWIFT_API_KEY (or pass --url and --key)
Why: The scanner has no address or key.
Fix: Export both variables, or pass --url and --key. For an offline trial, use --dry-run with --flags.
answered 401 or 403. Use an admin key that has the code_references:write scope
Why: The key is a client or server key, is revoked or expired, or lacks the scope.
Fix: Create an admin key for the project on the API Keys page and use that.
There are no flags to look for
Why: The project has no flags, or the key belongs to a different project than you expect.
Fix: Check the key's project on the API Keys page.
A flag you know is used shows no locations
Why: The key is built at runtime, or written without quotes (a constant or enum), or the file is ignored or over 1 MB.
Fix: Write the key as a string literal, try --loose, or check --ignore and the skipped folders.
A project can report from up to 50 repositories
Why: A typo in --repository created a new scan target each run.
Fix: Pass a stable --repository name in CI.