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

.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

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

.qodex.yaml reference

See every supported field.

Check Run and merge gating

Understand how Qodex can block merges.

Verification probes

Learn how preview checks are scoped.

How a review fires

Follow the full PR review lifecycle.

​.qodex.yaml overview

​What it controls

​Where to put it

​Default behavior

​Example

​When to add it

​Next steps