> ## 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. Use it to configure repository-level review 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](https://qodex.ai/docs/qodex-yaml-overview.md).

## `pr_review`

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

**pr\_review\.enabled** `boolean` (default: true)

Whether opening or pushing to a PR starts a review automatically. Set to `false` to make the repo review-on-request: Qodex skips automatic reviews with a neutral Check Run titled "Review on request", while `@qodex-ai review` and the **Run review** button in Qodex still start a review. Every review counts against the plan either way. This is the same setting as **Automatic reviews** in the repo's review settings in Qodex.

**pr\_review\.severity\_threshold** `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.

**pr\_review\.style\_placement\_threshold** `enum` (default: major)

Style and maintainability findings below this severity are collected into a collapsed walkthrough group instead of separate inline threads. Bugs, security, and performance findings still post inline. Supported values are `critical`, `major`, `minor`, `nitpick`, and `info`.

**pr\_review\.block\_pr\_merge** `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.

**pr\_review\.block\_on\_severity** `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`.

**pr\_review\.paths.exclude** `string[]` (default: \[])

Glob patterns for files Qodex should ignore. Supports `*`, `**`, and `?`. Negation and character classes are not supported.

**pr\_review\.disabled\_rules** `string[]` (default: \[])

Rule-source tokens to suppress, one per entry. Exact values and globs are supported, for example `lens:react-*`, `semgrep:javascript.lang.security.audit.path-traversal`, or `gitleaks:generic-api-key`. Agent-original findings without a rule source are not suppressed by this list.

**pr\_review\.authors** `string[]` (default: \[])

GitHub logins whose pull requests Qodex should review. Leave the list empty to review every author. Matching is case-insensitive.

**pr\_review\.base\_branches** `string[]` (default: \[])

Branches that pull requests must target to be reviewed. Leave the list empty to review pull requests into every branch. Exact names and globs such as `release/*` are supported.

## `review`

Names the repository files the reviewer reads as your team's rules, such as `CONTRIBUTING.md` or `AGENTS.md`.

**review\.instructions\_files** `string[]` (default: not set)

Paths from the repository root, read in the order you list them. Qodex reads this key only from the `.qodex.yaml` on the pull request's base branch, at the commit the pull request starts from, and reads each file there too. A pull request cannot add or change the list for its own review; a key that only the pull request's branch has is ignored. When the base branch has this key, it replaces the list of files chosen under **Files the reviewer reads** in Qodex, even when the list is empty; remove the key to use the list in Qodex again. A path with `..`, a leading slash, or one of `? # & = %` is not read, and the review says so. At most 50 paths.

Size limits for these files:

* A file over 32 KB is skipped whole. It is never cut.
* Files are read in order until 64 KB in all. Every file after that point is skipped whole.
* Every file that is skipped or missing is named in the review's walkthrough, with the reason. For example: "Not read: docs/x.md, 41 KB, over the 32 KB limit".
* A section between `<!-- openqodex:start -->` and `<!-- openqodex:end -->` is removed before the file is read. OpenQodex writes that section itself. Nothing else in the file is changed.

Your notes in Qodex have their own limit of 50,000 characters, separate from these files.

## `probes`

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

**probes.preview\_host\_allowlist** `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.

**probes.allow\_non\_get** `boolean` (default: false)

Controls whether non-GET verification probes can run. The default is `false`, so verification probes are GET-only.

## Complete example

```yaml theme={null}
pr_review:
  enabled: true
  severity_threshold: minor
  style_placement_threshold: major
  block_pr_merge: true
  block_on_severity: critical
  paths:
    exclude:
      - "*.md"
      - "vendor/**"
      - "**/*.generated.ts"
      - "test/fixtures/**"
      - "**/migrations/*.sql"
  disabled_rules:
    - "lens:react-*"
  authors:
    - "octocat"
  base_branches:
    - "main"
    - "release/*"

review:
  instructions_files:
    - "CONTRIBUTING.md"
    - "docs/style.md"

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 one exception is `review.instructions_files`, which Qodex reads only from the base branch.
* 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.
* The `@qodex-ai approve` command is enabled only from **Settings > PR review > Commands**. It cannot be enabled by a pull request's `.qodex.yaml` file.

## Next steps

> [card] [.qodex.yaml overview](https://qodex.ai/docs/qodex-yaml-overview.md)
>
> Learn when to add the file.

> [card] [Check Run and merge gating](https://qodex.ai/docs/pr-review-check-run.md)
>
> Configure branch protection around Qodex.

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

> [card] [Inline findings](https://qodex.ai/docs/pr-review-inline-findings.md)
>
> Understand where PR findings appear.


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