Open Code Review Toolkit

Open Code Review Toolkit is an unofficial review control and integration layer for Alibaba Open Code Review, with GitLab CI and standalone local providers. It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, local Markdown reports, and safe GitLab merge-request posting. It does not bundle or download the ocr binary.

Explore the toolkit site for a quick overview, demo video, and latest release notes.

Install

Python 3.12 through 3.14 is supported. Install the toolkit CLI in an isolated tool environment:

uv tool install open-code-review-toolkit

If uv is unavailable, use pip only inside an activated virtual environment; do not install the toolkit into a global Python environment:

python -m venv .venv
. .venv/bin/activate
python -m pip install open-code-review-toolkit

The toolkit does not bundle OCR. Use recommended_version in the compatibility manifest for this toolkit revision to select the exact upstream release. Download its platform asset, verify it against that release entry's asset SHA-256, and place the verified binary on PATH. Do not substitute the latest upstream release or use another toolkit revision's manifest.

Verify the installation without contacting an LLM provider:

ocr --version
ocr-ci --help

ocr --version must report the manifest's exact recommended_version; ocr-ci --help must exit successfully. ocr-ci preflight is an operational configuration check, not the installation smoke test.

The exact recommended OCR release and its verified asset checksums live in the versioned compatibility manifest. CI should pin that release and checksum before execution. The versioned compatibility policy records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases. Review output defaults to English. OCR_REVIEW_LANGUAGE accepts another explicit language name when a project needs localized review output; for example, OCR_REVIEW_LANGUAGE=Russian. The toolkit defaults OCR_REVIEW_EFFORT to medium for two review rounds. low and high are explicit one- and three-round alternatives; see the configuration reference for cost, budget, and precedence boundaries.

Stable distributions are published to PyPI and mirrored as checksum-listed, provenance-attested assets in the corresponding GitHub Release. Development snapshots are published only to TestPyPI.

Standalone local quick start

With the qualified OCR binary and LLM environment configured, review an immutable commit without forge credentials:

ocr-ci preflight --local
review_dir=$(mktemp -d)
review_dir=$(cd "$review_dir" && pwd -P)
ocr-ci review --local --result "$review_dir/review.json" --stderr "$review_dir/review.stderr" --report "$review_dir/review.md" -- --commit HEAD

Local execution uses the same OCR, mandatory evidence MCP, validation and DLP pipeline as CI. It publishes every admitted finding to a fresh private Markdown file and the console, without GitLab acquisition, suppression, approval or a fabricated publication receipt. See local review for ranges, failure behavior and optional private --debug-dir bundles. Local reviews keep custom API providers as the default and can optionally use OCR's native ChatGPT authentication.

Optional reasoning and progress controls do not change review rounds or budgets. Reasoning is unset by default; explicit none is a wire value whose support depends on the provider/model. Progress is off by default and emits only bounded toolkit phases to an interactive terminal or an explicitly nonblocking embedding stream; a conventional CI stderr pipe is intentionally not used because it can block a review.

How GitLab reviews evolve

On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with /ocr suppress or @<live-bot-username> suppress to keep a discussion open without future repeats; use the corresponding resolve command to resolve it after the next successful posting transaction. For example, a bot named mr.bot accepts the exact reply @mr.bot resolve.

Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See GitLab review operations for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.

After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v11's exact reviewed diff, actual target, policy authority, merge-request author, DLP mode, and reconciled federation use. This write is enabled by default; set OCR_AUTO_APPROVE=false when the bot must remain comment-only. DLP-clean metadata, generic discussions, protected same-revision CI outcomes, unused governed services, and successful review_read tool use do not independently block approval. An unprotected target, disabled DLP, degraded metadata, a DLP rejection, required context degradation, admitted remediation history, older receipts, publication filtering, used advisory tools, uncertain federation accounting, author movement, or bot self-authorship prevents an approval write. A CI status is review context, never approval authority. GitLab approval rules, Code Owners, and protected-branch policy remain authoritative merge policy. They are not prerequisites for OCR execution. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.

An intentionally absent toolkit receipt retains compatible direct posting outside GitLab CI without automatic approval. A present v9/v10 receipt can be read for historical diagnostics, but cannot publish a new current MR review.

Accepted tradeoffs can be recorded in .opencodereview/accepted-decisions.md; the evidence collector supplies only applicable decisions from the selected policy commit and never lets a source change self-authorize its review. Root and nested policy AGENTS.md/CLAUDE.md guidance is similarly exposed through the existing evidence MCP with deterministic scope and precedence, while any guidance touched by the merge request is excluded. See Accepted project decisions and Target project guidance for formats and trust boundaries.

Project architecture

The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, literal search, scoped absence checks, and base/head changes through the mandatory built-in read-only MCP server. GitLab reviews can also expose a bounded, separately labelled actual-target snapshot for relevant code context; it does not become policy or another reviewed delta. The internal server is always present and cannot be removed or replaced by operator configuration. Protected-policy enriched reviews can also acquire stable GitLab discussions, verified remediation history, and protected same-revision CI outcomes before OCR. Optional external tools use the governed registry-v2 federation gateway: the toolkit freezes explicit allowlists, validates schemas, origins, DLP and budgets, and reconciles content-free usage receipts while OCR remains the only model loop. Local review permits explicit HTTPS or stdio upstreams; GitLab permits HTTPS only.

• Toolkit strategy - durable product boundaries, architecture, invariants, and non-goals.
• Bounded review context - protected policy, GitLab discussions and same-revision CI outcomes, legacy reference migration, opaque handles, DLP, receipt, and cleanup contracts.
• Roadmap - milestone status, dependencies, outcomes, and completion signals.
• Backlog - inactive implementation-ready work; active execution remains in PLANS.md.

GitLab CI quick start

1. Configure protected/masked GITLAB_API_TOKEN and LLM variables in GitLab.
2. Pin and checksum the OCR binary.
3. With toolkit 0.13.0, leave OCR_GITLAB_TARGET_PROTECTION_MODE unset to use its auto default for a single MR targeting an unprotected branch under the same project's protected default-branch policy. Select explicit required to reject unprotected targets, or unprotected for the earlier limited profile.
4. Merge repository review configuration, including the Rules path, into the protected policy branch before relying on it.
5. Enable the CI review job in a later merge request and install this package.
6. Run the four public helper stages around ocr review:

ocr-ci preflight
ocr-ci configure
review_result="/tmp/ocr-result-${CI_JOB_ID}.json"
review_stderr="/tmp/ocr-stderr-${CI_JOB_ID}.log"
ocr-ci review --result "$review_result" --stderr "$review_stderr" -- ... --format json || export OCR_EXIT_CODE=$?
ocr-ci post --result "$review_result" --stderr "$review_stderr"

See the GitLab mode matrix, the complete ocr-review.gitlab-ci.yml pipeline, the GitLab setup guide, and GitLab review operations.

The two-merge-request setup is recommended because repository Rules must already exist on the captured policy commit. For a protected target that is its own authority; for an unprotected target in auto, it is the protected default branch. The integration MR can add Rules and CI together when it need not be reviewed: its first run may stop with setup-pending, and later MRs work after the policy change merges. Retrying the same MR cannot promote its source Rules. An unprotected target in explicit unprotected mode with missing target Rules fails closed. A green advisory job or pipeline does not prove that OCR or its model executed. See the GitLab setup guide for the exact boundary.

Configuration and safety

Configuration is environment-driven. The configuration reference documents supported OCR_*, CI_*, GITLAB_*, and MCP inputs. Posting requires GITLAB_API_TOKEN; job tokens and legacy aliases are deliberately unsupported.

Repository content, OCR output, and provider responses are untrusted inputs. The toolkit applies bounded reads and writes, secret redaction, Unicode normalization, Markdown/quick-action neutralization, fingerprinted comments, ownership boundaries for human replies, and rollback controls. Review the security and trust model before enabling write access.

Development and release

• Documentation index
• Contributing
• Code of Conduct
• Development guide
• Security policy
• Release process
• Changelog

Licensed under Apache-2.0.