> ## 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 overview

> Add .qodex.yaml to a repository when you want repo-specific control over Qodex PR review.

# .qodex.yaml overview

`.qodex.yaml` is the repo-level configuration file for Qodex PR review.

Most repositories can start without it. When the file is missing, Qodex uses safe defaults: PR review is enabled, merge blocking is off, generated paths are not excluded, and verification probes are limited.

Add the file when one repository needs a different review policy than the rest of your projects.

## What it controls

Use `.qodex.yaml` to control:

* Whether Qodex reviews PRs in this repo.
* The minimum severity shown in PR comments.
* Whether verified findings can fail the Qodex Check Run.
* Which paths Qodex should ignore.
* Which preview hosts Qodex may probe.
* Whether non-GET verification probes are allowed.

## Where to put it

Place the file at the root of the GitHub repository:

```text theme={null}
.qodex.yaml
```

For each review, Qodex reads the file from the PR head SHA. If a PR changes `.qodex.yaml`, the next review uses the version from that PR branch.

If the file is missing, larger than 16 KB, or invalid YAML, Qodex falls back to defaults instead of failing the review.

## Default behavior

| Setting                         | Default    | Meaning                                                   |
| ------------------------------- | ---------- | --------------------------------------------------------- |
| `pr_review.enabled`             | `true`     | Qodex reviews PRs.                                        |
| `pr_review.severity_threshold`  | `minor`    | Critical, major, and minor findings are shown.            |
| `pr_review.block_pr_merge`      | `false`    | Qodex is advisory by default.                             |
| `pr_review.block_on_severity`   | `critical` | If blocking is enabled, critical verified findings block. |
| `pr_review.paths.exclude`       | `[]`       | No paths are excluded.                                    |
| `probes.preview_host_allowlist` | `null`     | Global safe-probe rules apply.                            |
| `probes.allow_non_get`          | `false`    | Verification probes stay GET-only.                        |

Unknown fields are ignored, so newer Qodex config fields do not break older parsers.

## 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"

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

## When to add it

Add `.qodex.yaml` when:

* Qodex findings should block merges for this repo.
* Generated, vendored, fixture, or migration files should be ignored.
* Verification probes should be limited to approved preview hosts.
* One repo needs stricter or looser review rules than another.

Skip it when the defaults are enough.

## Next steps

<CardGroup cols={2}>
  <Card title=".qodex.yaml reference" icon="file-code" href="/qodex-yaml-reference">
    See every supported field.
  </Card>

  <Card title="Check Run and merge gating" icon="shield-check" href="/pr-review-check-run">
    Understand how Qodex can block merges.
  </Card>

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

  <Card title="How a review fires" icon="webhook" href="/pr-review-how-it-fires">
    Follow the full PR review lifecycle.
  </Card>
</CardGroup>