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 latest private-registry images and artifact-first verification.

What this guide covers

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

GitLab merge request pipelines
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 release image in the GitLab review job:

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.
AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS set to the exact normalized provider base URL for the first real non-mock run.

Authentication is required before pulling images.

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.

Minimal public GitLab job shape

Keep the first 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

Readiness before the first real run

Before rollout, run the same readiness checks in the same environment the job will use:

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

Confirm before you widen rollout:

the review job can reach the provider endpoint
the provider/model settings are present
the trust-gate allowlist exactly matches the normalized provider base URL
.ai-review/ai-review.md and .ai-review/ai-review.json are published as artifacts
the first run stays artifact-first

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

A first real non-mock run fails with exit 11 if the allowlist is empty or does not match the normalized provider base URL.

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 --gitlab-readiness --semantic-readiness.
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
keep the rollout artifact-first until the team is comfortable with the baseline

Installation and Upgrades