preflight-gate

Preflight Gate

Overview

A preflight gate answers one question right before you flip a switch: is the live environment actually configured to run this safely? It is not a code audit (that's ground-truth-audit) and not a diff review. It is the last check between "the code is ready" and "real money / real email / real user data is now in motion."

Core principle: A preflight gate is fail-closed. Anything you could not positively verify is a NO-GO. "Probably fine" is NO-GO. The cost of a false GO is a real charge to a real card, a broken redirect after a real payment, or prod data written against a half-applied schema — things you cannot take back.

Two rules dominate everything below. Internalize them before running any check.

Cardinal Rule 1 — Never put a secret value in your output

Verifying that a secret exists does not require seeing its value. Printing, echoing, cat-ing, or Read-ing a secret means the value lands in your context, the transcript, and any logs — and once it's there, the only safe response is rotation.

Verify presence and shape, value-blind:

Goal	Safe (value-blind)	Never
Is the var set?	test -n "$VAR" && echo set || echo MISSING	echo $VAR, cat .env*
Is it in the file?	grep -cE '^VAR=' .env.local (count)	grep '^VAR=' .env.local (prints value)
Right shape/prefix?	[[ "$VAR" == sk_live_* ]] && echo live-prefix	pasting the key to "show" the prefix
Right length?	echo "${#VAR}"	pasting the value

To demonstrate a mismatch, describe it — don't paste it. If two credentials belong to different accounts, write "the account identifier embedded in the key differs from the one in the price id," not the two strings. If a discriminator must be shown, mask it (sk_live_…AAA111). The reader does not need the secret to act on it.

If a secret value enters your context anyway — you ran the wrong command, a tool printed a file — STOP. Tell the user, and walk them through rotation. That rotation is now the task; do not continue preflight as if nothing happened.

Cardinal Rule 2 — Live facts come from live systems

The production database's migration version, whether a service is deployed and running, whether a webhook is registered in a dashboard, what environment variables are set in the hosting platform — these are live facts. Read them from the live system: the prod DB, the platform CLI/API, the provider dashboard.

A repo file, a .prod-db-version, a README, or a RELEASE_CHECKLIST.md that describes production is a claim, not production. A checklist saying "migrations applied" is evidence that someone ticked a box, nothing more. Never substitute a repo artifact for a live check — that is how a half-migrated prod database gets a GO.

The Method

0. Name the switch and what it makes irreversible

State exactly what you're flipping (test → live keys, staging → prod DB, sandbox → production) and what becomes irreversible the moment you do: real charges, real emails, real user-data writes. This sets the stakes and the ordering.

1. Build the gate list from the live path's real dependencies

Walk the path that goes live and list every external system it touches — payments, database, queue, email, storage, auth, domain/DNS, monitoring. For each, write the single condition that must be true to go live.

2. Classify each check: local-verifiable vs live-only

• Local-verifiable: presence/shape of env vars, mode/account consistency — run these value-blind (Rule 1).
• Live-only: prod DB state, deployed-service status, dashboard registrations, platform env vars — run the actual live check, naming the command or dashboard (Rule 2). Do not infer from a repo file.

3. Reconcile mode and account

Every credential on the live path must be (a) the right mode — live, not test/sandbox — and (b) the same account/project. A live key with a sandbox price, or a key and a price from two accounts, fails at runtime. Check consistency without printing the secrets.

4. Fail closed

Any item not positively verified is NO-GO. A single UNVERIFIED live-only item blocks go-live until it's checked. Do not round "couldn't confirm" up to "fine."

5. Verify, don't remediate

Preflight changes nothing. If an item fails, stop, report it, fix it in a separate deliberate step, then re-run the whole gate — a fix can invalidate an earlier pass.

6. Order by blast radius

Put the irreversible-once-live items first (anything that charges, sends, or writes real data), then breaking-but-recoverable, then degraded. The reader should see the scariest gap at the top.

Output Template

Always use this structure:

# [Switch] Preflight — [date]

## Verdict: GO / NO-GO
One line. If NO-GO, the count of blockers and unverified items.

## Gate
| Item | System | Check type (local/live) | Result (PASS/FAIL/UNVERIFIED) | How checked |
Each row: how you checked is value-blind for secrets, a live check for live facts.

## Blockers
Ordered by blast radius. Each: what's wrong, the consequence once live,
and the fix (applied separately, then re-run the gate). Describe secret
mismatches — never paste secret values.

## Live checks still required before GO
Every live-only item not yet confirmed, with the exact command or dashboard
that confirms it. Each of these is a NO-GO until done.

## Go-live sequence (once all green)
Ordered steps, ending in a real end-to-end smoke test of the live path.

Common Mistakes

Mistake	Fix
Pasting a secret value to "show evidence"	Verify value-blind; describe mismatches, mask discriminators
Trusting a repo file / checklist for prod state	Read live state from the live system
"The secret is set" ⇒ "the service is configured"	A webhook secret present ≠ the webhook registered. Separate checks
Rounding "couldn't verify" up to PASS	Fail closed — UNVERIFIED is NO-GO
Fixing a failed item in place mid-preflight	Verify only; fix separately; re-run the whole gate
Ordering by discovery instead of blast radius	Irreversible-once-live items first

Red Flags — stop immediately

• About to cat, echo, or Read a .env* or secret file → use a value-blind check.
• Quoting a key's prefix or token "just to show it" → describe it instead, or mask it.
• Reading prod DB version / deploy status / webhook state from a repo file → that's a claim; run the live check.
• About to write GO with any row marked UNVERIFIED → fail closed, it's NO-GO.
• A real secret value appeared in your output → stop, surface it, rotate. That's the task now.