Skip to main content

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

​
pr_review

Controls whether Qodex reviews PRs, which findings are shown, and whether the Qodex Check Run can fail.
​
pr_review.enabled
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.
​
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.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.

​
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

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

.qodex.yaml overview

Learn when to add the file.

Check Run and merge gating

Configure branch protection around Qodex.

Verification probes

See how preview checks are scoped.

Inline findings

Understand where PR findings appear.