Skip to content
FlagSwiftDocs

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.mjs from the FlagSwift repository. It has no dependencies.
  • An admin API key for the project, with the code_references:write scope. 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 needs flags.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#

  1. 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.
  2. 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-run

    The 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-run to try it offline.
  3. Run it in CI

    Run the same command, without --dry-run, on your main branch, with the key in a secret. Use --repository to 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.
  4. 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.
  5. 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#

Scanner options
OptionDescription
--url, --keyThe server address and the admin key. Or set FLAGSWIFT_URL and FLAGSWIFT_API_KEY.
--repositoryThe name shown in the console (FLAGSWIFT_REPOSITORY), up to 200 characters.
--dirThe folder to scan. Defaults to the current folder.
--flagsA file of flag keys, one per line, instead of fetching them.
--looseCount a key anywhere in code, not only inside quotes. Finds more, and adds false matches.
--ignoreAn extra folder or file name to skip. Repeat it for several.
--dry-run, --jsonPrint 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, build and .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

The scanner is one script that matches text, so it works with any language. If you want something else, report from your own tooling with 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.

Request
# 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 }] }
    ]
  }'
Report response
{
  "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

References are as fresh as the last run on the branch you scan. Scan your main branch, and expect a flag removed on a feature branch to stay listed until that branch is merged and scanned.
Does scanning send my source code to FlagSwift?
No. Only the repository name, branch, commit, and the flag key with its file path and line number leave your CI. No file contents are sent.
I have several repositories. How do I scan them?
Run the scanner in each, with its own --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?
The report is replaced only when the next scan runs on that repository. Run the job, or wait for the next push to main.
Can a server key run the scanner?
A server key can list the flag keys, but reporting needs an admin key with 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.