astradevlabsastradevlabs
← All posts
Tools4 min

Field Guide: Audit Feature-Flag Rollouts with Vercel CLI Version History

Tools

Feature flags let teams deploy code before they release it, but that separation creates a new operational question: when production behavior changes, who changed the flag, what changed, and which environment was affected?

Vercel answered that question on July 23 with vercel flags versions. The command exposes a flag's revision history in the CLI, including the author, message, timestamp, and changed environments. A companion diff command compares one revision with the revision immediately before it and reports changes to rules, rollout percentages, and conditions.

That sounds like a small CLI addition. In practice, it closes a useful gap between shipping a rollout and explaining it during an incident.

1. Start with the complete history

Update to the latest Vercel CLI, then inspect the flag involved in a rollout:

bash
vercel flags versions checkout-redesign

The first pass should answer four questions: which revision happened near the incident, who authored it, whether a message explains the intent, and which environments changed. Do not jump straight to the newest revision. A production symptom may come from an earlier percentage increase that only became visible as more users entered the treatment group.

Treat this output as the flag's timeline, not as a replacement for application logs. It tells you how configuration moved. Logs and traces still tell you what the application did after evaluation.

2. Narrow the search to the affected environment

Development, preview, and production can carry different configurations. If the report concerns production, remove unrelated revisions from the first investigation:

bash
vercel flags versions checkout-redesign --environment production

This matters because a safe preview test and a risky production rule can share the same flag name while behaving differently. Vercel's flag model supports separate environment configurations, including static values, targeting rules, and inherited configurations. Filtering prevents a busy cross-environment history from hiding the change that matters.

3. Read the semantic diff

Once you identify a suspicious revision, compare it with its predecessor:

bash
vercel flags versions diff checkout-redesign --revision 42

The diff is semantic rather than a generic text comparison. It highlights field-level additions, removals, and modifications across targeting rules, rollout percentages, and conditions. That makes the output useful for reviewers who understand release intent but do not want to decode a raw configuration document during an outage.

Look for three common failure patterns:

  • A rollout percentage increased faster than monitoring could validate.
  • A condition widened from a narrow cohort to a broad customer segment.
  • Rule ordering changed, causing an earlier match to shadow the intended rule.

Vercel rules evaluate from top to bottom, so ordering is behavior. A correct-looking condition can still produce the wrong result if another rule now matches first.

4. Save machine-readable evidence

For a repeatable incident workflow, request JSON and keep the result with the incident record:

bash
vercel flags versions checkout-redesign --environment production --json

Use --limit and --cursor when the history is long. The goal is not to build another flag-management system. It is to preserve the exact revisions you reviewed so a later postmortem does not depend on screenshots or memory.

A small script can also compare the latest revision metadata with a deployment window or alert timestamp. Keep that automation read-only. Rollbacks should remain explicit until the team has enough evidence to define safe automated criteria.

5. Connect history to the current rule set

Version history explains how the flag arrived at its current state. The current rules explain what will evaluate now:

bash
vercel flags rules ls checkout-redesign --environment production --json

Vercel added CLI rule management earlier in July, including support for entity conditions, reusable segments, weighted splits, and progressive rollouts. Reading both outputs gives responders a better sequence: identify the revision, inspect the change, then verify the resulting rule order and outcome.

6. Turn the commands into a rollback checklist

Use a short operational checklist whenever a flag is suspected:

  1. Record the incident start time and affected environment.
  2. List flag revisions for that environment.
  3. Diff the revision nearest the start time.
  4. Inspect the current ordered rules.
  5. Correlate the change with logs, analytics, and error rates.
  6. Decide whether to pause, narrow, or reverse the rollout through the normal approval path.

This workflow keeps the CLI in its best role: fast inspection with scriptable output. It does not replace monitoring, change approval, or a tested rollback procedure.

Bottom line

vercel flags versions turns feature-flag history into something developers and agents can inspect without leaving the terminal. The valuable part is not the command itself. It is the tighter loop between a production symptom, the exact configuration revision, and the rule behavior that followed. Add the history and diff commands to the same runbook that already covers deployments, logs, and rollback ownership.

References