How OpenCodeReview Manages Code Review Workflows: Architecture and Implementation

OpenCodeReview orchestrates a deterministic-plus-agent pipeline that extracts Git diffs, generates AI-powered line-level comments via configurable LLMs, and publishes structured feedback to GitHub, GitLab, Gerrit, and other CI platforms.

The alibaba/open-code-review repository provides a deterministic engine for managing code review workflows through a hybrid architecture that combines hard-coded file handling with dynamic AI analysis. This open-source tool transforms raw Git changes into actionable review comments by processing diffs through a multi-layer pipeline that guarantees no changed files are missed while leveraging large language models for contextual feedback.

The Three-Layer Architecture for Code Review Workflow Management

OpenCodeReview implements a deterministic core plus dynamic LLM processing to manage code review workflows safely and consistently.

Layer 1: Diff Extraction and File-Level Preparation

The foundation of the workflow is a deterministic engine written in Go that eliminates variability in file handling. Located in src/main.go and supporting packages, this layer reads Git diffs—whether staged, unstaged, untracked, or specific commit ranges—and performs precise file selection and bundling.

The core logic generates a deterministic review plan that matches each file against configured rule sets and bundles related files together. This engineering guarantees no missed files and consistent rule application across every review run, providing the safety-critical infrastructure that ensures every changed line is examined according to the same criteria.

Layer 2: Agent-Driven Review Generation

Once the file bundles are prepared, the ocr review CLI command invokes a configurable LLM to produce actual review comments. This agent-driven layer uses scenario-tuned prompts and a curated toolset to focus the model on narrowed contexts—processing one bundle at a time rather than overwhelming the context window with entire repositories.

The agent returns a structured JSON payload containing inline comments, warnings, and summaries. Users can customize this behavior via the Review Rules configuration system, allowing the LLM to adhere to project-specific coding standards while maintaining the deterministic structure of the output.

Layer 3: Platform-Specific Publishing

The final layer consists of thin "glue" scripts that read the JSON output and publish comments to target platforms in atomic requests. These scripts handle platform-specific API requirements:

• Gerrit: The script in examples/gerrit_ci/post_review.py builds a ReviewInput object and POSTs to {GERRIT_URL}/a/changes/{change}/revisions/{revision}/review, handling XSSI prefix stripping and authentication
• GitLab: examples/gitlab_ci/post_review.py converts JSON into GitLab's comment API format
• Other platforms: Analogous scripts support GitFlic, Codeup, and generic GitHub implementations

These publisher scripts include resilience mechanisms such as retry logic and comment folding when platforms reject batches, ensuring reliable delivery of review feedback regardless of network conditions or API limitations.

Session Management for Resilient Workflows

OpenCodeReview manages code review workflows with interruption tolerance through a session-based persistence system. Each review run is stored as a session, enabling users to list historical reviews, resume interrupted pipelines, or view comments later using the CLI.

Key session commands include:

# List all review sessions

ocr session list

# View comments from a specific session

ocr session comments <session-id>

# Resume an interrupted review

session_id=$(ocr session list | tail -1 | cut -d' ' -f1)
ocr review --resume $session_id

This session handling, implemented in cmd/ocr/main.go, enables long-running CI pipelines to survive interruptions and allows developers to manually replay or inspect reviews without re-running expensive LLM inference.

Practical Implementation Examples

To run a full-repository scan that reviews every file:

cd my-project
ocr scan

For diff-based reviews comparing branches:

ocr review --from main --to feature-branch

To publish a review to Gerrit within a CI job:

python3 examples/gerrit_ci/post_review.py \
    --input /tmp/ocr-result.json \
    --change $CI_MERGE_REQUEST_IID \
    --revision $CI_COMMIT_SHA \
    --gerrit-url $GERRIT_URL

Key Files in the Repository

Understanding how OpenCodeReview manages code review workflows requires familiarity with these critical components:

• src/main.go: Implements the deterministic core including diff extraction, file bundling, rule matching, and session handling
• cmd/ocr/main.go: CLI entry point for ocr review, ocr scan, and ocr session commands
• examples/gerrit_ci/post_review.py: Production-ready Gerrit publisher with authentication, XSSI stripping, and retry logic
• examples/gitlab_ci/post_review.py: GitLab-specific implementation of the publishing layer
• examples/gerrit_ci/post_review_test.py: Unit tests validating the Gerrit publishing logic and error handling

Summary

• Deterministic core: The Go-based engine in src/main.go guarantees every changed file is examined through precise diff extraction and rule matching
• Agent integration: The ocr review command delegates contextual analysis to configurable LLMs while maintaining structured JSON output
• Platform abstraction: Publisher scripts in examples/ handle platform-specific APIs for Gerrit, GitLab, and others with built-in retry and error handling
• Session persistence: The ocr session CLI enables interruption-tolerant workflows and manual review replay
• CLI flexibility: Commands like ocr scan and ocr review --from <base> --to <head> support both full-repository and incremental review strategies

Frequently Asked Questions

How does OpenCodeReview ensure no files are missed during a review?

The tool implements a deterministic review plan in the Go core (src/main.go) that processes Git diffs through precise file selection and bundling logic. This deterministic layer guarantees every changed file—whether staged, unstaged, or in a specific commit range—is matched against rule sets and included in the review bundle before any LLM processing begins.

What CI platforms does OpenCodeReview support for publishing reviews?

OpenCodeReview supports GitHub, GitLab, Gerrit, GitFlic, and Codeup through platform-specific publisher scripts. The Gerrit implementation in examples/gerrit_ci/post_review.py constructs ReviewInput objects and handles XSSI prefix stripping, while the GitLab script manages merge request discussions. These scripts convert the tool's standardized JSON output into platform-native API calls.

How does session management work in OpenCodeReview?

Each review run is persisted as a session accessible via ocr session list, allowing users to view historical comments with ocr session comments or resume interrupted workflows using ocr review --resume <session-id>. This system, implemented in the CLI layer, enables CI pipelines to survive interruptions without losing review state or requiring expensive re-processing.

Can I customize which files or rules the LLM applies during review?

Yes. The deterministic preprocessing layer matches files against configurable Review Rules before invoking the agent. This allows teams to define specific rule sets for different file types or directories, ensuring the LLM receives contextually appropriate prompts and coding standards for each bundle it processes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}