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

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

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
  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/*"

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

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