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 pinned GHCR images and artifact-first verification.

What this guide covers

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

GitLab merge request pipelines
GHCR image pinning with immutable tags
.ai-review artifact output
artifact-first rollout before optional feedback expansion

Self-hosted operator runbooks, pilot-only workflows, and maintainer troubleshooting stay outside this public guide.

Supported public installation mode

Use the PatchPatrol release image in the GitLab review job:

ghcr.io/aistack-projects/patchpatrol:vX.Y.Z
ghcr.io/aistack-projects/patchpatrol-semantic:vX.Y.Z (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.

Minimal public GitLab job shape

Keep the first rollout narrow and explicit:

patchpatrol_review:
  image: ghcr.io/aistack-projects/patchpatrol:vX.Y.Z
  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.

Upgrade and pinning

Upgrade by changing the pinned image tag in the GitLab review job:

Move the review job image from ...:vX.Y.Z to the new immutable version.
Rerun ai-review test --gitlab-readiness --semantic-readiness.
Validate one GitLab merge request run before widening rollout.

Use immutable tags:

Preferred: ghcr.io/aistack-projects/patchpatrol:vX.Y.Z
Avoid for ongoing environments: floating tags such as latest

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

Rollback behavior

Rollback by restoring the previous pinned image tag and 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