Policy Controls

Use this page to understand which supported control points teams are expected to change first and which posture PatchPatrol recommends for an initial rollout.

Source of truth: this page is derived from shipped PatchPatrol contracts and the checked-in support posture already documented for the public surface.

Recommended Starter Profile

Start with the narrowest public path that proves the workflow before you add more delivery noise or stricter gates:

AI_REVIEW_FEEDBACK_MODE=artifact-only
AI_REVIEW_PROVIDER=openai
OPENAI_BASE_URL="https://llm-gateway.internal/v1"
AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS="https://llm-gateway.internal/v1"
AI_REVIEW_MODEL="gpt-4o-mini"

ai-review test --gitlab-readiness --semantic-readiness

This starter posture keeps the first rollout artifact-first, validates readiness before a full review run, and prefers customer-controlled/self-hosted OpenAI-compatible endpoints for the public path. The official OpenAI API remains a supported fallback and quick-evaluation path when a customer-controlled endpoint is not ready yet. This starter profile only becomes a real-provider path when the allowlist exactly matches the normalized provider base URL.

If you want the exact variable surface behind these choices, go to the configuration reference. If you want the matching command flags, go to the CLI reference.

Versioning the starter profile

Once the starter posture is settled, you can check the safe defaults into the repository with a repo-root .ai-review.yml instead of repeating every value in CI variables.

PatchPatrol keeps the first schema intentionally narrow and versionable:

• use .ai-review.yml for stable defaults such as model, provider, fail_on, review_context_mode, include_globs, exclude_globs, feedback_mode, and enable_final_summary
• use .ai-review.yml review.rules for bounded repo-specific review guidance that should travel with the repository
• keep secrets, endpoint URLs, allowlist controls, and other trust-boundary settings in environment variables or deployment config

That split keeps the public control surface inspectable while preventing checked-in repo policy from silently weakening runtime safety posture.

Review rules are prompt guidance, not accepted findings. Use them when the team wants PatchPatrol to pay attention to repo-specific standards, such as requiring regression tests around changed runtime behavior. A rule can influence what the provider verifies, but it does not create an automatic finding or fail gate: findings still need concrete diff/context evidence.

Accepted findings use a different checked-in file: repo-root .ai-review-baseline.yml.

• use .ai-review.yml for stable review defaults
• use .ai-review.yml review.rules for prompt-only repository guidance
• use .ai-review-baseline.yml for accepted findings that have an exact artifact fingerprint and a reviewable reason

That separation keeps policy defaults distinct from the repository's accepted finding history and keeps prompt guidance distinct from suppression decisions.

When to Change Feedback Delivery

Keep AI_REVIEW_FEEDBACK_MODE=artifact-only while the team is still proving that artifacts are generated, readable, and trustworthy.

Move to mr when you want PatchPatrol to publish a summary note directly into merge request collaboration after the artifact-first path is already stable.

Move to mr-manual when you want the same MR delivery surface, but only on explicitly authorized runs. This is the safer escalation path when teams want occasional MR feedback without making it the default on every pipeline.

If you enable MR delivery, AI_REVIEW_GITLAB_INLINE_DISCUSSIONS=false keeps the owned summary note while suppressing inline discussion noise.

When to Tighten Review Gates

AI_REVIEW_FAIL_ON controls which validated severities block the run:

• Keep none when the team is still learning the signal and does not want findings to fail CI yet.
• Raise it to blocker, high, or medium when the review output is already trusted enough to become a policy gate.

If a finding is known and explicitly accepted, record it in .ai-review-baseline.yml instead of weakening the whole gate. PatchPatrol matches baseline entries by exact deterministic fingerprint, evaluates AI_REVIEW_FAIL_ON only against unsuppressed findings, and still keeps suppressed findings visible in artifact metadata and markdown.

AI_REVIEW_FAIL_ON_PARTIAL_COVERAGE is a separate strictness control:

• Keep it false when bounded omission is still acceptable during early rollout.
• Set it to true when you want any omitted chunk to fail the run, even without a severity hit.

The tradeoff is simple: stronger gates increase trust pressure, but they also make noisy rollout mistakes and oversized diffs more visible in CI.

How to Choose a Provider Path

PatchPatrol supports ollama, openai, and mock, but they serve different public purposes:

• openai: use this for customer-controlled/self-hosted OpenAI-compatible endpoints first, or the official OpenAI API as the supported fallback and quick-evaluation path.
• ollama: use this when your supported runtime is the dedicated Ollama provider path and the runner can reach OLLAMA_HOST.
• mock: use this for local planning, docs validation, and non-remote iteration when you want to skip provider calls entirely.

The tradeoff is not only cost or speed. It is also about trust boundary control: customer-controlled/self-hosted OpenAI-compatible endpoints keep review payload handling inside infrastructure you manage, while the official OpenAI API is easier to try quickly but moves that traffic onto a public hosted service.

Decision Table

Return to Reference.