# Configuration

`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

```yaml
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_analytics
```

## The project

`projectName` names the project in the report and on the [dashboard](https://preflight.sh/docs/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](https://preflight.sh/docs/stacks/#stack-values) 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](https://preflight.sh/docs/scanning/#json-output), 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](https://preflight.sh/docs/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](https://preflight.sh/docs/ignoring/#allowlisting-one-secret)). 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:

```text
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 CLI
```

Strictness 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.
