> ## 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. See when to add it and which controls it unlocks.

# .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: automatic PR review is on, 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 automatically, or only when someone asks with `@qodex-ai review` or the **Run review** button.
* 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.
* Which repository files the reviewer reads as your team's rules (`review.instructions_files`).

## 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. The one exception is `review.instructions_files`: Qodex reads it only from the base branch, so a PR cannot choose the rules it is reviewed by.

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` | Opening or pushing to a PR starts a review. Requested reviews run either way. |
| `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

> [card] [.qodex.yaml reference](https://qodex.ai/docs/qodex-yaml-reference.md)
>
> See every supported field.

> [card] [Check Run and merge gating](https://qodex.ai/docs/pr-review-check-run.md)
>
> Understand how Qodex can block merges.

> [card] [Verification probes](https://qodex.ai/docs/pr-review-verification-probes.md)
>
> Learn how preview checks are scoped.

> [card] [How a review fires](https://qodex.ai/docs/pr-review-how-it-fires.md)
>
> Follow the full PR review lifecycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.