Configuration Reference

Use this page when you need the exact public configuration contract for the supported PatchPatrol workflow after the quickstart path is already in place.

If you need the canonical support contract for runtime baselines and deployment modes before choosing settings, start with Supported runtime and operating modes.

Source of truth: this page is derived from shipped PatchPatrol contracts in patchpatrol/config.py and the checked-in configuration references that narrow those contracts to the supported public surface.

This is the baseline public configuration surface. For operator-tuned controls and explicitly scoped legacy compatibility entries, read the companion Advanced configuration page.

When the same setting exists in both an environment variable and the CLI, the CLI flag is the direct override. Use the CLI reference for command flags and Policy controls for change guidance.

Repo-local defaults with .ai-review.yml

PatchPatrol also supports an optional repo-root .ai-review.yml for versioned safe defaults. Resolution order is explicit:

1. built-in defaults
2. .ai-review.yml
3. environment variables
4. CLI overrides

Version 1 of .ai-review.yml intentionally supports only stable safe defaults and bounded prompt-only review rules that teams are most likely to version with the repository.

Supported defaults fields:

• model
• provider
• fail_on
• fail_on_partial_coverage
• review_context_mode
• incremental_mode
• include_globs
• exclude_globs
• feedback_mode
• remediation_mode
• enable_final_summary
• enable_review_lenses
• review_lenses

Supported review.rules fields:

• id: required stable identifier, up to 128 characters, using letters, numbers, ., _, :, and -
• severity: optional prompt-priority label: error, warning, or info
• scope: optional list of repository-path glob patterns; omitted or empty scope applies the rule to every reviewed path
• instruction: required non-empty review instruction, up to 1000 characters

PatchPatrol retains at most 50 repo-local rules from the policy file and renders at most 12 matched rules per prompt/chunk. Rules are prompt-only review constraints: they guide provider attention, but findings still require concrete diff/context evidence and do not become deterministic fail gates.

For the admin workflow, audit output, disablement behavior, and concrete privacy/testing/dependency/architecture examples, use Repository-aware rules.

Secrets, endpoint URLs, allowlist controls, output paths, numeric diff bounds, and executable hooks are intentionally outside the version 1 repo-local policy contract.

Example:

version: 1
defaults:
  provider: openai
  model: gpt-4o-mini
  fail_on: high
  feedback_mode: artifact-only
  remediation_mode: off
  review_context_mode: diff-only
  incremental_mode: auto
  include_globs:
    - src/**
  exclude_globs:
    - vendor/**
    - node_modules/**
review:
  rules:
    - id: require-regression-tests-for-runtime-behavior
      severity: warning
      scope:
        - "patchpatrol/**/*.py"
      instruction: "When runtime behavior changes, verify that tests cover the pre-fix failure mode and observable behavior."

Accepted findings with .ai-review-baseline.yml

PatchPatrol also supports an optional checked-in repo-root .ai-review-baseline.yml for accepted findings.

This file is distinct from .ai-review.yml:

• use .ai-review.yml for safe repo-local defaults such as provider, model, and review bounds
• use .ai-review-baseline.yml only for accepted findings that should stop tripping rollout gates while still remaining visible in artifacts

Version 1 is intentionally narrow and deterministic:

• the file name is fixed at the repository root
• entries live under suppressions
• each entry requires an exact finding fingerprint
• each entry requires a human-readable reason

Example:

version: 1
suppressions:
  - fingerprint: 0123456789abcdef
    reason: Accepted historical issue while rollout stays in advisory mode

On the next run, PatchPatrol applies the baseline before AI_REVIEW_FAIL_ON evaluation. That means fail-on policy evaluates only unsuppressed findings after baseline matching. Suppressed findings do not disappear silently: the artifacts still expose suppression evidence in markdown and JSON metadata so operators can see what matched and why.

Use the Developer Quickstart when you want the public artifact workflow for finding and copying a fingerprint, and use Policy controls when you are deciding whether accepted findings should remain advisory or block CI.

Provider and Runtime

Structured-output mode

AI_REVIEW_STRUCTURED_OUTPUT_MODE affects review calls only:

• json: the default JSON-object request shape and validation/retry path.
• json_schema: for OpenAI-compatible review calls, requests strict structured output with the PatchPatrol report schema. If the endpoint returns a clear unsupported-schema response, PatchPatrol retries that review call with JSON-object mode.
• auto: currently uses the same OpenAI-compatible schema request and deterministic unsupported-schema fallback as json_schema.

Ollama review calls keep the broadly compatible JSON path. PatchPatrol records only compact mode counters and reason codes under meta.limits; it does not persist raw prompts or provider request payloads in review artifacts.

Self-Hosted License

Non-dry-run review work with AI_REVIEW_PROVIDER=ollama or AI_REVIEW_PROVIDER=openai requires a valid Self-Hosted License before source or diff extraction and before provider calls. Configure exactly one runtime source:

If both variables are set, PatchPatrol reports LICENSE_SOURCE_AMBIGUOUS and exits 12. An unreadable file reports LICENSE_FILE_READ_FAILED; a missing source for real-provider review work reports LICENSE_MISSING. License inputs are runtime-only and do not belong in .ai-review.yml or GitLab component inputs.

Validate the configured source without running a review or calling a provider:

ai-review license inspect --json

Inspection exits 0 only when the license is valid. Every other License Status exits 12 and returns non-sensitive JSON with stable LICENSE_* reason codes. Mock-provider runs, dry-runs that stop before provider calls, and non-chat readiness checks remain available without a license.

Review Bounds and Semantic Context

These review bounds are built-in defaults for the supported baseline path when the environment variable is left unset. Raise them explicitly for larger runs, or clear a specific bound by setting its environment variable to an empty string when you are deliberately opting out and want an unbounded/None posture.

For the operational difference between diff-only and diff+semantic, read Review context mode.

Optional high-stakes review lenses

Review lenses are disabled by default. When enabled, PatchPatrol can run additional bounded provider calls for configured lenses only when deterministic signals match touched paths, repo-local review rules, preflight hints, or high-stakes file patterns.

Supported lenses are correctness, security, test-integrity, migration-rollout, and external-contract. Each lens uses the same visible diff/chunk, prompt-context byte budget, strict JSON validation, line anchoring, corrective retry, and invalid-output fallback behavior as the base review. Lens findings merge into the standard report and still go through dedupe, validation, suppressions, and artifact rendering.

Cost and latency increase with the number of executed lens calls. A run may execute no lens calls when heuristics do not match; a chunked high-stakes diff can execute one or more additional provider calls per matching chunk. Enable lenses for high-stakes categories such as auth, billing, migrations, tests, or external API contracts rather than as a default for every repository.

Lens visibility is recorded in ai-review.json under meta.limits with fields such as review_lenses_selected, review_lens_execution_count, review_lens_attempts, review_lens_fallback_count, review_lens_reason_codes, and review_lens_usage when the provider reports usage.

Incremental GitLab MR review

AI_REVIEW_INCREMENTAL_MODE affects GitLab MR runs only:

• auto: default. If PatchPatrol can read a prior reviewed head SHA from its owned MR summary note, resolve that SHA, and confirm it is an ancestor of the current head, the provider reviews only the new delta.
• always: uses the same safe incremental checks as auto; unsafe ranges still fall back to full MR review with explicit metadata.
• never: disables incremental provider scope.

Incremental review does not change GitLab line anchoring. PatchPatrol keeps the full MR diff refs for inline eligibility and records the decision under meta.incremental_review in ai-review.json.

Delivery and Policy Controls

Optional provider allowlist

Set the allowlist to the exact normalized provider base URL when you want PatchPatrol to restrict non-mock provider calls to known endpoints:

OPENAI_BASE_URL="https://llm-gateway.internal/v1"
AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS="https://llm-gateway.internal/v1"

OLLAMA_HOST="http://ollama.internal:11434"
AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS="http://ollama.internal:11434/"

If AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS is unset or empty, PatchPatrol skips endpoint allowlist enforcement. If it is set and the normalized provider endpoint does not match, the trust gate blocks before remote calls.

If you are wiring the first supported public path, start with Admin Quickstart and return here for the exact variable contract.

Exit Semantics

Most teams only need a short mental model for exit behavior:

• 0: no configured gate was tripped.
• 12: Self-Hosted License evaluation blocked real-provider review work before provider calls.
• 10: AI_REVIEW_FAIL_ON or AI_REVIEW_FAIL_ON_PARTIAL_COVERAGE triggered a review gate.
• 11: PatchPatrol stopped before remote calls because the trust gate blocked execution.
• 8: invalid-output fallback occurred.

Public Boundary

• AI_REVIEW_POST_MR_NOTE is retained as a backwards-compatible alias for existing installs and maps to AI_REVIEW_FEEDBACK_MODE=mr through AI_REVIEW_FEEDBACK_MODE resolution.
• Variables not listed on this page and not covered on the companion page are outside the published public contract.

Use Policy controls when you are choosing how strict those gates should be, and use the CLI reference when you need the matching command-line overrides.

Return to Reference.