Configuration Reference
Exact public configuration coverage for the supported PatchPatrol workflow.
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.
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.
Provider and Runtime
| Variable | Default | Supported values or posture | Public meaning |
|---|---|---|---|
AI_REVIEW_MODEL | deepseek-coder-v2:16b | Non-empty model identifier | Selects the review model used for run and readiness checks. |
AI_REVIEW_PROVIDER | ollama | ollama, openai, mock | Chooses the provider path: Ollama, OpenAI-compatible endpoints, or mock iteration. |
OLLAMA_HOST | http://192.168.19.55:11434 | Valid http or https URL | Endpoint used when AI_REVIEW_PROVIDER=ollama. |
OPENAI_BASE_URL | unset | Required when AI_REVIEW_PROVIDER=openai; valid http(s) API root without query or fragment | Points PatchPatrol at a customer-controlled/self-hosted OpenAI-compatible endpoint or the official OpenAI API fallback. |
OPENAI_API_KEY | unset | Secret value when the endpoint requires auth | Supplies bearer-token auth for OpenAI-compatible requests. |
OPENAI_ORGANIZATION | unset | Optional header value | Adds the OpenAI-Organization header when the endpoint supports it. |
OPENAI_PROJECT | unset | Optional header value | Adds the OpenAI-Project header when the endpoint supports it. |
AI_REVIEW_OUTPUT_DIR | .ai-review | Writable path | Controls where PatchPatrol writes ai-review.md, ai-review.json, and related artifacts. |
AI_REVIEW_TIMEOUT_SECONDS | unset | Positive integer or unset | Sets a provider-neutral request timeout and takes precedence over OLLAMA_TIMEOUT_SECONDS. |
OLLAMA_TIMEOUT_SECONDS | unset | Positive integer or unset | Backwards-compatible timeout alias for the Ollama path; ignored when AI_REVIEW_TIMEOUT_SECONDS is set. |
AI_REVIEW_TRANSPORT_RETRY_MAX_ATTEMPTS | 2 | Positive integer; 1 disables retry | Bounds retryable provider and GitLab transport attempts for CI predictability. |
Review Bounds and Semantic Context
| Variable | Default | Supported values or posture | Public meaning |
|---|---|---|---|
AI_REVIEW_MAX_DIFF_BYTES | unset | Positive integer or unset | Caps total diff bytes considered for review. |
AI_REVIEW_MAX_FILES | unset | Positive integer or unset | Caps how many changed files PatchPatrol selects for review. |
AI_REVIEW_MAX_CHUNKS | unset | Positive integer or unset | Caps the number of reviewable chunks after filtering and ordering. |
AI_REVIEW_MAX_FILE_DIFF_BYTES | unset | Positive integer or unset | Caps diff size per file chunk and omits oversized files with reason metadata. |
AI_REVIEW_CONTEXT_MODE | diff-only | diff-only, diff+semantic | Chooses plain diff review or the best-effort semantic precheck path. |
AI_REVIEW_SEMANTIC_TOTAL_TIMEOUT_SECONDS | 20 | Positive integer | Sets the total timeout budget for semantic precheck work when diff+semantic is enabled. |
AI_REVIEW_MAX_SUPPORTING_CONTEXT_BYTES | 65536 | Positive integer | Caps the bounded supporting context carried into semantic-aware prompts. |
Delivery and Policy Controls
| Variable | Default | Supported values or posture | Public meaning |
|---|---|---|---|
AI_REVIEW_FAIL_ON | none | none, blocker, high, medium | Chooses which validated finding severities turn ai-review run into a non-zero gate. |
AI_REVIEW_FAIL_ON_PARTIAL_COVERAGE | false | true or false | Fails the run when omitted chunks are present, even if no severity threshold was hit. |
AI_REVIEW_ENABLE_FINAL_SUMMARY | false | true or false | Enables an extra summary-only model pass that can refine top issues without changing deterministic findings. |
AI_REVIEW_FEEDBACK_MODE | artifact-only | artifact-only, mr, mr-manual | Keeps the blessed artifact-first baseline or turns on GitLab merge request delivery. |
AI_REVIEW_GITLAB_INLINE_DISCUSSIONS | true | true or false | When MR delivery is active, decides whether PatchPatrol also posts eligible inline discussions. |
AI_REVIEW_ALLOW_DRAFT_MR_FEEDBACK | false | true or false | Allows MR delivery on draft or WIP merge requests for the current run. |
AI_REVIEW_MANUAL_FEEDBACK_AUTHORIZED | false | true or false | Explicitly authorizes mr-manual delivery when CI metadata alone should not decide it. |
AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS | unset | Comma-separated exact normalized http(s) base URLs | Required exact normalized provider base URLs for non-mock providers before the first real review run. |
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_ONorAI_REVIEW_FAIL_ON_PARTIAL_COVERAGEtriggered 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_NOTEis retained as a backwards-compatible alias for existing installs and maps toAI_REVIEW_FEEDBACK_MODE=mrthroughAI_REVIEW_FEEDBACK_MODEresolution.- 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.