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
• include_globs
• exclude_globs
• feedback_mode
• enable_final_summary

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.

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
  review_context_mode: diff-only
  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.

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.

Delivery and Policy Controls

Trust-gate prerequisite for first real runs

Set the allowlist to the exact normalized provider base URL before the first real non-mock review run:

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