Configuration
Copy MarkdownConfiguration
preflight init writes preflight.yml to your project’s root. Commit it, so every machine and every CI run scans the same way.
An example
projectName: my-app
stack: rails # rails, next, react, vite, laravel and so on
urls:
staging: "https://staging.example.com"
production: "https://example.com"
services:
stripe:
declared: true
sentry:
declared: true
checks:
envParity:
enabled: true
envFile: ".env"
exampleFile: ".env.example"
healthEndpoint:
enabled: true
path: "/health" # optional: with enabled: true, only this path is checked
stripeWebhook:
enabled: true
url: "https://api.example.com/webhooks/stripe" # optional: probed with a GET
seoMeta:
enabled: true
mainLayout: "app/views/layouts/application.html.erb"
security:
enabled: true
secrets:
enabled: true
allowlist:
- path: web/js/golden-hour.js
fingerprint: "sha256:<hex>"
reason: "HTTP-referrer-restricted Google Timezone key"
indexNow:
enabled: true
key: "0123456789abcdef0123456789abcdef" # 32 hex characters
emailAuth:
enabled: true # opt-in: SPF and DMARC
domain: mail.example.com # optional: the domain you send mail from
humansTxt:
enabled: false # opt-in: credits the team
license:
enabled: false # opt-in: for open source projects
ignore:
- sitemap
- llms_txt
- google_analyticsThe project
projectName names the project in the report and on the dashboard. stack tells the checks where to look: which layout holds the meta tags, where the public files live, which package manager to audit. preflight init detects it; supported stacks lists the values.
URLs
urls.production and urls.staging are where the network checks go: ssl, security_headers, www_redirect, health_endpoint, and the checks that read the rendered page. preflight init asks for both, and both are optional. Without a URL, the network checks never pass: ssl, www_redirect, and health_endpoint stay out of the scan, security_headers is reported as skipped, and the page checks read your templates instead.
Network checks connect directly and do not use HTTP_PROXY or HTTPS_PROXY. Preflight looks at each address before it connects and refuses private ones, and a proxy would make that connection out of its sight. On a network that only reaches the internet through a proxy, the network checks report the site as unreachable; run them from a machine with direct access.
Services
Each entry under services: says whether the project uses that service. A declared service that never gets initialized is reported. See services for the IDs.
preflight init lists every service it knows, most with declared: false. A service ID this version doesn’t know is dropped with a note when it has declared: false, since a newer Preflight may have written it, and is an error when it has declared: true, since that is most likely a typo. The old groq ID is read as grok, with a note to rename it.
Checks
Keys under checks: turn checks on or off and give them settings. They are camelCase (seoMeta, envParity), a separate schema from the snake_case check IDs.
An opt-in check runs only when its block is here. preflight init writes envParity and secrets turned on, and security turned on when it is given a production URL, so most projects have them; a hand-written file without those blocks leaves the three checks out.
A block without an enabled: key turns its check on (since 1.1): writing secrets.allowlist or envParity.envFile is asking for that check. Before 1.1 such a block left an opt-in check off without saying so. Only enabled: false turns a check off, and a key with nothing under it (secrets: on its own) changes nothing. healthEndpoint runs by default whenever a URL is set, and seoMeta whenever a layout or URL is found, so a block that only sets path or mainLayout leaves them on as well. One block is the exception: healthEndpoint: {enabled: false, path: /health}, exactly, is what preflight init used to write for CMS and static sites, so it keeps its old meaning (the check still runs when a URL is set) and prints a note saying how to turn it off. init no longer writes it.
| Key | Settings |
|---|---|
envParity |
envFile and exampleFile, compared for missing variables. Both must be paths inside the project. Opt-in |
healthEndpoint |
path, when it isn’t one of the usual ones. Without enabled, it is tried first, then the usual ones; with enabled: true, only it is |
stripeWebhook |
Turns on the Stripe check (result ID stripe), which looks for the API keys, the webhook secret, and the SDK’s initialization. url is optional and is probed with a GET; a 404 or no answer is reported. Opt-in: declaring stripe under services: is not enough on its own |
seoMeta |
mainLayout, the template that holds your <head>. It must be a path inside the project |
security |
Turns on the security_headers check. Opt-in |
secrets |
allowlist, for findings you have checked (see ignoring checks). Opt-in |
indexNow |
key, your IndexNow key. Opt-in |
emailAuth |
Turns on the SPF and DMARC check. Opt-in. domain is the domain you send mail from. Without it, the check uses the production URL’s host, then its organizational domain (www.example.com, then example.com), and says so in its message; with no production URL either, it is skipped |
adsTxt, humansTxt, license |
Turn on these file checks. Opt-in |
Ignore
ignore: lists the check and service IDs to leave out of every scan. preflight ignore <id> and preflight unignore <id> edit it for you. An entry with a /, *, or . is a path glob instead, and leaves matching files out of the source checks (vendor/**). A bare word that is neither an ID nor a glob, like vendor, loads with a note: it matches only a file of that name at the project root.
Strict loading
Preflight reads preflight.yml strictly, so a typo can’t silently turn a check off. A file path that leaves the project (a leading /, or any ..) in envFile, exampleFile, or mainLayout stops the scan with exit 64 too. An unknown key stops the scan with exit 64 and says where it is:
Error: failed to parse preflight.yml: unknown key "bogus" under checks: at line 5. Check the spelling; if this file was written by a newer Preflight, upgrade the CLIStrictness cuts both ways: a newer Preflight may write keys an older one rejects. When a teammate’s preflight init adds a key your CLI doesn’t know, upgrade the CLI rather than deleting the key.