flag-drift-audit

flag-drift-audit

Multi-environment feature-flag setups drift silently: a flag gets added in staging and forgotten in production, a rollout percentage gets bumped in one environment and not another, or a flag outlives its purpose and nobody removes it. These are the JSON exports most flag providers already let you download - this project diffs them properly.

What it detects

• Missing flags - present in one environment, absent from another
• Value drift - a flag exists everywhere but its default value or rollout percentage differs across environments
• Stale/orphaned flags - flags marked "unused": true, or untouched for longer than a configurable threshold via lastModified

Usage

flag-drift-audit [options] <env1.json|dir> <env2.json|dir> [...more envs]

Two environments:

node bin/flag-drift-audit.js fixtures/staging.json fixtures/production.json

Three or more environments, or a directory of exports:

node bin/flag-drift-audit.js fixtures/staging.json fixtures/production.json fixtures/development.json
node bin/flag-drift-audit.js ./flag-exports/

See examples/ for worked comparisons with checked-in expected output, including a realistic multi-flag, multi-environment scenario in examples/realistic/.

Example output

Console report for fixtures/staging.json, fixtures/production.json, and fixtures/development.json compared together:

Options

Flag	Description
-f, --format <console|json|markdown>	Report format (default: console)
-o, --output <path>	Write the report to a file instead of stdout
--stale-days <N>	Age threshold for stale flags (default: 90)
--ignore-keys <a,b>	Comma-separated flag keys to ignore in drift comparison
--strict	Fail if any config has an invalid flag shape
--fail-on-drift	Exit with code 2 if drift is found
--no-color	Disable ANSI color in console output
-h, --help	Show help
-v, --version	Show version

CI usage

Gate a pipeline on flag drift with --fail-on-drift, which sets exit code 2 when any missing or drifted flags are found (1 on usage errors, 0 when clean):

flag-drift-audit --fail-on-drift staging.json production.json || exit 1

See examples/ci-usage.yml for a copy-pasteable GitHub Actions job.

Use as a GitHub Action

- uses: aks-builds/flag-drift-audit@main
  with:
    files: flags/staging.json flags/production.json
    fail-on-drift: "true"
    format: markdown

Directory input

Instead of listing files, point at a directory of exports and each *.json file inside becomes one environment:

flag-drift-audit ./flag-exports/

Exit codes

Code	Meaning
0	No usage error; drift may or may not have been found
1	Usage error (bad arguments, fewer than two files, unreadable/invalid config)
2	--fail-on-drift was set and drift or missing flags were found

Troubleshooting

• "Cannot read config file" - the path does not exist or is not readable; check for typos or permissions.
• "Invalid JSON in ..." - the file is not valid JSON; open it in an editor with JSON linting to find the exact syntax error.
• Directory produced 0 environments - the directory has no JSON files directly inside it (subdirectories are not scanned recursively).
• "Cannot write report to ..." - the --output path's parent directory does not exist; create it before running the command.

Status

1.0.0: the CLI surface is stable. Drift, stale-flag detection, and strict validation work end to end against fixture, example, and realistic multi-environment configs, with console, JSON, and Markdown report formats and optional file output via --output.

Tags

feature-flags devops cli config-drift release-engineering