Admin Quickstart

This quickstart helps a workspace admin take a team from prerequisites to a running first review path.

Supported public path: GitLab artifact-first

Start with the GitLab artifact workflow and keep the first rollout in artifact-only mode.

This guide covers the supported public SaaS path. Deeper operator, self-hosted, and private-rollout variants are outside this guide.

Outcomes

• Understand the minimum setup sequence for the supported public path.
• Configure the repository and review job for a first successful run.
• Hand the running review flow over to developers and shared follow-on docs.

1. Check prerequisites

Start with the minimum requirements for the public GitLab path:

• A GitLab project with merge request pipelines enabled.
• Runner access to the selected provider endpoint.
• A pinned PatchPatrol image such as ghcr.io/aistack-projects/patchpatrol:vX.Y.Z.
• Admin access to the CI variables and pipeline configuration for the project.

Success check

• You know which GitLab project will host the first review flow.
• You can edit CI variables for that project.
• You have a reachable provider endpoint and a model choice for the first run.

2. Confirm access and roles

The admin owns invitations, repository setup, CI configuration, and the first review handoff. The developer needs access to open merge requests, view pipeline results, and read the generated review artifacts.

Use Access and roles as the canonical page for invitations, role handoffs, and the minimum token and membership steps required for the supported public path.

Success check

• You know which actions stay with the admin and which actions move to the developer.
• Developers know they should wait for the setup handoff before expecting a runnable review flow.

3. Connect the GitLab project

Set PatchPatrol up on the GitLab project that will host the first review workflow:

• Add the PatchPatrol review job to merge request pipelines.
• Make sure the target branch is fetchable from the runner.
• Keep the workflow centered on merge request review rather than local-only or operator-only variants.

Success check

• A merge request pipeline exists for the project.
• The review job is attached to that path instead of a separate internal-only workflow.

If you need the public install and upgrade walkthrough for the supported GitLab artifact-first path, use Installation and upgrades.

4. Configure the review path

Keep the first setup narrow and explicit. The supported public baseline is:

• PATCHPATROL_IMAGE=ghcr.io/aistack-projects/patchpatrol:vX.Y.Z
• AI_REVIEW_OUTPUT_DIR=.ai-review
• AI_REVIEW_FEEDBACK_MODE=artifact-only
• AI_REVIEW_MODEL=<supported model>
• AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS=<exact normalized provider base URL(s)>
• AI_REVIEW_PROVIDER=ollama with OLLAMA_HOST=<reachable endpoint> or AI_REVIEW_PROVIDER=openai with OPENAI_BASE_URL=<reachable endpoint> and OPENAI_API_KEY when required

Keep the first rollout in artifact-only mode so the team can verify the generated outputs before enabling optional merge request feedback.

Trust-gate prerequisite for real providers

Add the allowlist before the first non-mock run:

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_PROVIDER=ollama
OLLAMA_HOST="http://ollama.internal:11434"
AI_REVIEW_PROVIDER_ALLOWLIST_BASE_URLS="http://ollama.internal:11434/"

Mock runs skip remote provider calls, so the allowlist prerequisite only applies to non-mock providers.

Use Configuration Reference for the exact variable contract and Troubleshooting when a trust-gate failure blocks the run.

Example: first public review job

Use a narrow job shape for the first rollout:

patchpatrol_review:
  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

What to notice: the PatchPatrol review job is the proof point. For the first run, it only needs to finish, publish .ai-review artifacts, and keep MR note delivery optional.

Success check

• The review job has a pinned PatchPatrol image.
• Artifact output is enabled under .ai-review.
• The provider endpoint, model, feedback mode, and allowlist are configured for the first run.

5. Run readiness checks

Before the first review run, validate the path in the same environment the job will use:

• Run ai-review test --gitlab-readiness --semantic-readiness as a non-mutating preflight.
• Confirm the job can reach the provider endpoint and GitLab context it needs.
• Resolve missing access, provider, or merge request context issues before you ask developers to rely on the flow.

Success check

• The readiness checks exit cleanly.
• You can explain what a developer should do next without adding setup caveats.

6. Open the first review flow

Open or update a merge request so the configured review job runs on the supported path. The first successful admin outcome is a running review flow that produces the expected artifacts for developers to inspect:

• .ai-review/ai-review.md
• .ai-review/ai-review.json

Once the flow is running, hand the team forward to the Developer quickstart and First review output.

Success check

• The merge request pipeline runs the PatchPatrol review job.
• The review job produces ai-review.md and ai-review.json.
• Developers can move to the next guide without needing admin-only setup details.