Install and run PatchPatrol with the supported public path, then manage safe version upgrades.

Installation and Upgrade

This page helps workspace admins start PatchPatrol on the supported public path and upgrade safely without leaving the public docs surface.

Supported public path: GitLab artifact-first

Use this guide when you are setting up the first supported GitLab merge request review path with a pinned component include, latest private-registry images behind the component job, and artifact-first verification.

What this guide covers

This public guide covers the supported GitLab artifact-first path only:

GitLab merge request pipelines
pinned GitLab component includes when the component is available on the same GitLab instance
private-registry image usage with latest as the default client tag
.ai-review artifact output
artifact-first rollout before optional feedback expansion

Operator runbooks and maintainer troubleshooting stay outside this public guide.

If you are deciding whether your environment is in scope before you install, read Supported runtime and operating modes first.

Supported public installation mode

Use the PatchPatrol GitLab component include when your GitLab instance has access to the published component release:

include:
  - component: $CI_SERVER_FQDN/patchpatrol/components/gitlab-review@1.0.0
    inputs:
      feedback-mode: artifact-only
      readiness-mode: 'off'
      output-dir: .ai-review
      artifact-expire-in: 7 days

Pin the component reference to the SemVer release published for your instance; do not use @latest for component references. Self-managed GitLab instances may need a mirrored or local component project, local Catalog setup, and a published local SemVer release before the include works. Keep component readiness-mode off for artifact-only rollout; enable GitLab readiness only when MR feedback is enabled and the job has the required token/context.

The component job uses the PatchPatrol release image:

registry.patchpatrol.ai/patchpatrol:latest
registry.patchpatrol.ai/patchpatrol-semantic:latest (optional semantic-ready variant)

This path requires:

Docker available on the CI runner.
A GitLab project with merge request pipelines.
A reachable provider endpoint (OLLAMA_HOST for default Ollama, OPENAI_BASE_URL for OpenAI-compatible providers).
Access to CI variables for image and review configuration.
Artifact output under AI_REVIEW_OUTPUT_DIR=.ai-review.
AI_REVIEW_FEEDBACK_MODE=artifact-only for the first rollout.
Exactly one Self-Hosted License runtime source for real-provider work: PATCHPATROL_LICENSE or PATCHPATROL_LICENSE_FILE.
Optional AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS set to the exact normalized provider base URL when endpoint allowlist enforcement is required.

Authentication is required before pulling images.

Keep stable repo review policy in .ai-review.yml when appropriate. Keep provider endpoint values, provider credentials, registry credentials, allowlist controls, and optional GitLab feedback tokens in masked/protected GitLab CI/CD variables. Do not check secret values into .gitlab-ci.yml or .ai-review.yml.

First use flow

Authenticate non-interactively and pull the default image:

printf '%s\n' "$PATCHPATROL_REGISTRY_PASSWORD" | docker login registry.patchpatrol.ai --username "$PATCHPATROL_REGISTRY_USERNAME" --password-stdin
docker pull registry.patchpatrol.ai/patchpatrol:latest

Use latest by default so new review-process improvements land automatically. If you need to stay on a particular patch version, replace latest with vX.Y.Z.

Direct job fallback

Use the direct job shape only when the component is not available on the target GitLab instance or when you need a custom/private image workflow. Keep the first fallback rollout narrow and explicit:

patchpatrol_review:
  image: registry.patchpatrol.ai/patchpatrol:latest
  # The runner must be configured with DOCKER_AUTH_CONFIG or pre-authenticated
  # to pull the job image from registry.patchpatrol.ai before script runs.
  # See: https://docs.gitlab.com/ee/ci/docker/using_docker_images.html#access-an-image-from-a-private-container-registry
  script:
    - ai-review run --mode mr
  variables:
    AI_REVIEW_OUTPUT_DIR: .ai-review
    AI_REVIEW_FEEDBACK_MODE: artifact-only
  artifacts:
    paths:
      - .ai-review/ai-review.md
      - .ai-review/ai-review.json
      - .ai-review/ai-review.html

Readiness before the first real run

Before artifact-only rollout, run the same provider/config readiness check in the same environment the job will use:

ai-review test --chat --readiness-json

Real-provider chat probes require a valid Self-Hosted License from PATCHPATROL_LICENSE or PATCHPATROL_LICENSE_FILE. A license failure exits 12 before provider calls; dry-runs, mock-provider checks, and non-chat readiness checks remain available without a license.

Confirm before you widen rollout:

the review job can reach the provider endpoint
the provider/model settings are present
any configured trust-gate allowlist exactly matches the normalized provider base URL
readiness.metadata.failure_categories is empty, or its category tells you the next concrete fix
.ai-review/ai-review.md, .ai-review/ai-review.json, and .ai-review/ai-review.html are published as artifacts
the first run stays artifact-first

Use ai-review test --gitlab-readiness --readiness-json only before enabling MR feedback with the required GitLab token/context.

Use these exact examples for the supported public path:

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/"

When AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS is unset or empty, PatchPatrol does not enforce provider endpoint allowlisting. When it is set, a non-matching provider base URL fails before remote calls with exit 11.

If you are still setting up workspace ownership or repository wiring, go back to Workspace admin.

Update strategy and pinning

Most clients should keep latest in the GitLab review job and pull before each run. That keeps the review process aligned with the most recent improvements.

If you need to hold a specific patch version, switch from latest to vX.Y.Z, then:

Update the review job image from ...:latest to the required ...:vX.Y.Z.
Rerun ai-review test --chat --readiness-json with a valid Self-Hosted License for real-provider chat probes.
Validate one GitLab merge request run before widening rollout.

Use tags this way:

Preferred for most clients: registry.patchpatrol.ai/patchpatrol:latest
Use when you need a specific patch version: registry.patchpatrol.ai/patchpatrol:vX.Y.Z

For release-source context inside the public surface, continue with Release and versioning.

Rollback behavior

Rollback by switching from latest to the required previous vX.Y.Z image tag, then rerunning the same readiness check plus one merge request validation run.

Verify the first successful install path

Once the job is running on the supported path:

open .ai-review/ai-review.md first
confirm .ai-review/ai-review.json exists for structured detail
confirm .ai-review/ai-review.html exists for printable review output
keep the rollout artifact-first until the team is comfortable with the baseline

Installation and Upgrades