> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# .qodex.yaml reference

> Reference for every supported .qodex.yaml field, default, and behavior.

# .qodex.yaml reference

This page lists every supported `.qodex.yaml` field.

All fields are optional. Missing or invalid values fall back to defaults. If you want the product-level explanation first, start with the [.qodex.yaml overview](/qodex-yaml-overview).

## `pr_review`

Controls whether Qodex reviews PRs, which findings are shown, and whether the Qodex Check Run can fail.

<ParamField path="pr_review.enabled" type="boolean" default="true">
  Set to `false` to opt this repo out of Qodex PR review. Qodex skips the review and posts a neutral Check Run with the opt-out reason when possible.
</ParamField>

<ParamField path="pr_review.severity_threshold" type="enum" default="minor">
  Lowest severity Qodex shows in PR review. Supported values are `critical`, `major`, `minor`, `nitpick`, and `info`. The default `minor` shows critical, major, and minor findings.
</ParamField>

<ParamField path="pr_review.block_pr_merge" type="boolean" default="false">
  Set to `true` when verified findings should be able to fail the Qodex Check Run. Branch protection must require the Qodex check before this blocks a merge.
</ParamField>

<ParamField path="pr_review.block_on_severity" type="enum" default="critical">
  Lowest verified severity that fails the Check Run when `block_pr_merge` is enabled. Supported values are `critical`, `major`, `minor`, `nitpick`, and `info`.
</ParamField>

<ParamField path="pr_review.paths.exclude" type="string[]" default="[]">
  Glob patterns for files Qodex should ignore. Supports `*`, `**`, and `?`. Negation and character classes are not supported.
</ParamField>

## `probes`

Controls verification probes that Qodex may run against PR preview deployments.

<ParamField path="probes.preview_host_allowlist" type="string[] | null" default="null">
  Hostnames Qodex is allowed to probe. A pattern starting with `*.` matches the bare domain and subdomains. Use `null` for the global safe-probe guard. Use `[]` to block probes for every host.
</ParamField>

<ParamField path="probes.allow_non_get" type="boolean" default="false">
  Controls whether non-GET verification probes can run. The default is `false`, so verification probes are GET-only.
</ParamField>

## Complete example

```yaml theme={null}
pr_review:
  enabled: true
  severity_threshold: minor
  block_pr_merge: true
  block_on_severity: critical
  paths:
    exclude:
      - "*.md"
      - "vendor/**"
      - "**/*.generated.ts"
      - "test/fixtures/**"
      - "**/migrations/*.sql"

probes:
  preview_host_allowlist:
    - "*.vercel.app"
    - "preview.acme-staging.com"
  allow_non_get: false
```

## Behavior notes

* Qodex fetches `.qodex.yaml` from the PR head SHA.
* The file must be 16 KB or smaller.
* Invalid YAML falls back to defaults.
* Unknown fields are ignored.
* Merge blocking works only when branch protection requires the Qodex Check Run.
* Path excludes are applied after severity filtering.

## Next steps

<CardGroup cols={2}>
  <Card title=".qodex.yaml overview" icon="file-code" href="/qodex-yaml-overview">
    Learn when to add the file.
  </Card>

  <Card title="Check Run and merge gating" icon="shield-check" href="/pr-review-check-run">
    Configure branch protection around Qodex.
  </Card>

  <Card title="Verification probes" icon="zap" href="/pr-review-verification-probes">
    See how preview checks are scoped.
  </Card>

  <Card title="Inline findings" icon="message-square" href="/pr-review-inline-findings">
    Understand where PR findings appear.
  </Card>
</CardGroup>