Architecture

PatchPatrol runs in a CI job or local process and calls the model endpoint configured for that run. You choose the runner and network environment.

On the GitLab artifact-first path, the configured GitLab runner prepares the repository and job environment. The operator selects the runner and configures its variables, permissions, and network access. PatchPatrol selects bounded source context, sends it to the configured model endpoint, validates the response, and writes Run Reports.

A customer-controlled model endpoint can stay inside infrastructure you manage, but the configured endpoint may still be remote. Configuring it does not make it PatchPatrol-operated.

Review flow and boundaries

Scope: the sections below document current behavior in the ai-review run pipeline, including how failures are reported.

What happens when ai-review run starts

The command runs these stages:

1. Read effective configuration from environment and command flags.
2. Resolve a diff plan (auto, mr, branch, staged, working-tree).
3. Build a bounded review scope:
   • file include/exclude filtering,
   • file-level and total-size guardrails,
   • chunking and omission tracking.
4. For GitLab MR runs, decide whether the provider can review an incremental delta since the prior PatchPatrol-reviewed head SHA.
5. Run trust checks before any provider call.
6. Run optional semantic precheck (only in diff+semantic context mode).
7. Collect repository overview signals.
8. Execute provider review and validate the structured output.
9. Emit artifacts (ai-review.json, ai-review.md, ai-review.html, optional code_quality output).
10. Optionally run GitLab MR feedback, depending on AI_REVIEW_FEEDBACK_MODE and environment.

Input and Output Boundaries

Inputs

• Working tree/diff data from the selected git context.
• Run configuration and runtime limits from flags/environment.
• Optional repository overview evidence (file structure + detected tooling signals).
• Optional local semantic diagnostics when AI_REVIEW_CONTEXT_MODE=diff+semantic.

Processing boundaries

• Diff scope is bounded by fail-fast limits before provider execution.
• Review inputs are filtered into bounded chunks before provider review.
• If provider output is invalid for schema, PatchPatrol retries once and then emits an explicit fallback report.

Outputs

• ai-review.json is the canonical machine-readable Run Report for one execution.
• ai-review.md is the operator-readable Markdown Run Report.
• ai-review.html is the printable HTML Run Report.
• gl-code-quality-report.json is written when code-quality export is enabled in runtime config.
• The optional persistent GitLab Review Summary and separate inline discussions are written only when delivery is configured.

Trust Gate

Before any provider call, PatchPatrol evaluates the configured Trust Gate controls. A failed gate stops provider review and records the failure state in the generated artifacts.

Use Security & Privacy for the exact data-handling stages and the Configuration reference for endpoint policy settings and defaults.

Review execution behavior

• The review phase builds prompts from bounded diff content and repository context.
• In GitLab MR incremental mode, the provider can receive only the new delta since the prior PatchPatrol-reviewed head SHA. PatchPatrol still keeps full MR diff refs for inline eligibility and records the decision in meta.incremental_review.
• Prompts may include bounded supporting context under AI_REVIEW_MAX_SUPPORTING_CONTEXT_BYTES. When present, that context is packed in priority order: matched repo-local review rules, deterministic preflight review hints, chunk-local supporting code evidence, relevant semantic diagnostics, and repository overview.
• Deterministic preflight hints can highlight duplicate added code-like text, dependency additions, risky import additions, and missing test-counterpart signals before provider review. They are prompt evidence only: the provider must verify the signal against diff/context evidence before reporting a finding, and hints do not become automatic findings or fail gates.
• Review prompts may annotate added and context lines with prompt-only L<number>: labels to help providers anchor findings to new/right-side lines. Final line_start and line_end artifact fields remain normal integer file line numbers; the prompt labels are not persisted.
• The default review-call output mode remains JSON-object/JSON compatible.
• When AI_REVIEW_STRUCTURED_OUTPUT_MODE=json_schema or auto is used with an OpenAI-compatible provider, PatchPatrol can request strict JSON-schema output for review calls and fall back to JSON-object mode if the endpoint rejects schema mode.
• On invalid provider output, PatchPatrol attempts a fallback validation strategy.
• All report content is still validated against the shipped artifacts schema before writing.
• Usage and runtime metadata are attached to the JSON report for transparency.
• Structured-output mode decisions are recorded only as compact meta.limits.structured_output_* metadata; raw prompts and provider request payloads are not persisted in artifacts.
• Preflight hint metadata is also compact; raw prompt bodies, raw hint evidence, and provider chain-of-thought are not available in artifacts.

For exact command flags and environment variables, see:

• CLI reference
• Configuration reference

Why these boundaries are explicit

The sequence records configured scope limits, the Trust Gate result, provider response validation, and the JSON, Markdown, and HTML Run Reports. Operators can inspect those control points before enabling optional GitLab feedback.

Evidence and next steps

• Use Security & Privacy for credential, redaction, provider-processing, and retention responsibilities across these boundaries.
• Use the Configuration reference for exact provider, endpoint, scope, and artifact settings.
• Review the trust and rollout settings in Policy controls.
• Follow the Admin Quickstart for the GitLab artifact-first setup.
• Inspect First review output to see how the generated Run Reports are used.

Visit the PatchPatrol product website

for the short product overview.

Discuss a private GitLab review pilot

to review these boundaries in your environment.