Open Code Review Toolkit

Open Code Review Toolkit is an unofficial GitLab CI integration layer for Alibaba Open Code Review. It provides bounded repository context generation, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does not bundle or download the ocr binary.

[!NOTE] The project is under active development. It currently targets Python 3.10-3.14 on Linux and macOS; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.

Install

Install the Python package from PyPI and install a supported OCR binary separately:

python -m pip install open-code-review-toolkit
ocr --version
ocr-ci --help

The current compatibility target is OCR 1.8.0. CI should pin the release and verify its published 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. Set OCR_REVIEW_LANGUAGE=Russian to use Russian consistently in both OCR configuration and generated review context.

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.

How 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 to keep a discussion open without future repeats, or /ocr resolve to suppress it and resolve the discussion after the next successful posting transaction.

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.

Project-wide accepted tradeoffs can be recorded separately in .opencodereview/accepted-decisions.md; the context generator supplies them to OCR only when the current merge request is not changing that file. See Accepted project decisions for the entry format, inline marker convention, security boundary, and limitations.

Project development

The project is evolving from bounded background generation toward a shared Repository Evidence Engine: one deterministic evidence model will support both a compact OCR bootstrap and a built-in read-only MCP server. Development is ordered by outcomes and dependencies rather than speculative dates.

• Toolkit strategy - durable product boundaries, architecture, invariants, and non-goals.
• 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. Install this package.
4. Run the five helper stages around ocr review:

ocr-ci preflight
ocr-ci configure
ocr-ci mcp-config
ocr-ci context --output .review-context/dependencies.md
ocr-ci review --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log -- ... --format json
ocr-ci post --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log

See the fully synthetic examples/gitlab/ocr-review.gitlab-ci.yml, the GitLab setup guide, and GitLab review operations.

Configuration and safety

Configuration is environment-only in v0.1. 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

• Contributing
• Development guide
• Security policy
• Release process
• Changelog

Licensed under Apache-2.0.