Choose How OCR Runs in a Team

OpenCodeReview’s core pipeline can run locally, inside CI, or as deterministic scaffolding for another coding agent. This chapter turns that architecture into an operational choice: what should remain in OCR, who supplies the model, who publishes findings, and what data crosses the boundary? The reader should be able to choose an OCR-managed, CI-published, or host-agent-delegated setup without losing the scope, coverage, and privacy distinctions established earlier.

The integration surface matters because a review can be technically sound and still fail as a team process. A CI job may post to the wrong commit, a retry may duplicate comments, a host agent may receive more repository context than intended, or a provider configuration may silently combine credentials from unrelated sources. OCR’s integrations are useful when they preserve the same boundary discipline as the core review.

Keep review generation separate from platform publication

The cleanest CI design treats OCR as a review generator and the platform integration as a publisher. The CLI runs in range mode with machine-readable JSON and an agent audience, so standard output contains a payload rather than a progress conversation. The payload includes status, resolved model identity, aggregate usage, comments, warnings, session information, and, where available, a coverage manifest. A GitHub Actions or GitLab job then maps those comments to the platform’s review API.

This separation has practical value. OCR can keep its core output model independent of GitHub and GitLab’s different positioning rules, permissions, and retry behavior. The publisher can handle platform-specific details without changing the agent’s interpretation of the code. A team can also consume JSON for a custom dashboard or SARIF for code-scanning systems without pretending that every destination has the same comment semantics.

Credentials are split as well. The LLM credential lets OCR generate findings; a repository or merge-request token lets the CI layer post them. A secure workflow keeps those roles distinct and passes pull-request-controlled values through environment variables rather than interpolating them into shell code. Range review also needs the runner to have enough Git history to compute the intended merge-base. A job that installs the CLI correctly but checks out a shallow repository can still fail before the model sees the change.

Publication is not a single write. A finding with a valid line range may become an inline comment; one without a trustworthy location belongs in a summary. GitHub’s reusable Action can keep one sticky summary comment updated, skip new inline comments that overlap the bot’s existing history, route selected low-severity or category findings to the summary, and split large reviews into bounded batches. Those choices reduce timeline noise without deleting history. A finding skipped by incremental overlap remains represented in the counts and summary behavior rather than being mistaken for a new clean review.

The publisher also embeds identifiers so ambiguous writes can be reconciled. If a review request times out after possibly reaching GitHub, the retry path checks whether its tagged review or comments already exist. If the read API cannot establish the answer, it avoids posting a duplicate and exposes the uncertainty. The same design appears in the GitLab publisher, which uses per-comment identifiers and checks whether a discussion landed before retrying.

Cross-push checkpoints make the same principle visible at the PR level.