@alibaba-group/open-code-review 1.1.8 → 1.1.9

package/CONTRIBUTING.md

@@ -151,7 +151,6 @@ Documentation is a crucial part of OpenCodeReview. We welcome improvements to RE
 | `README.zh-CN.md`       | Chinese translation                  |
 | `CONTRIBUTING.md`       | Contribution guide (English)         |
 | `CONTRIBUTING.zh-CN.md` | Contribution guide (Chinese)         |
-| `NPM-README.md`         | Description shown on npm registry    |
 
 ## Submitting Changes
 

package/CONTRIBUTING.zh-CN.md

@@ -151,7 +151,6 @@ make build
 | `README.zh-CN.md`       | 中文翻译             |
 | `CONTRIBUTING.md`       | 贡献指南（英文）     |
 | `CONTRIBUTING.zh-CN.md` | 贡献指南（中文）     |
-| `NPM-README.md`         | npm 发布页展示的说明 |
 
 ## 提交变更
 

package/README.md

@@ -1,8 +1,67 @@
-# OpenCodeReview CLI
+<p align="center">
+  <a href="https://alibaba.github.io/open-code-review/">
+    <img src="imgs/logo.svg" alt="OpenCodeReview logo" width="240" height="240">
+  </a>
+</p>
+<p align="center">The open source AI code review agent.</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@alibaba-group/open-code-review"><img alt="npm" src="https://img.shields.io/npm/v/@alibaba-group/open-code-review?style=flat-square" /></a>
+  <a href="https://github.com/alibaba/open-code-review/actions/workflows/release.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/alibaba/open-code-review/release.yml?style=flat-square" /></a>
+  <a href="https://github.com/alibaba/open-code-review/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/alibaba/open-code-review?style=flat-square" /></a>
+</p>
+<p align="center">
+  English | <a href="README.zh-CN.md">简体中文</a>
+</p>
 
-AI-powered code review tool that reads Git diffs, sends changed files to a configurable LLM via OpenAI-compatible API, and generates structured review comments. It goes beyond surface-level analysis — the Agent can read project context for deep reviews.
+---
 
-## Install
+## What is Open Code Review?
+
+Open Code Review is an AI-powered code review CLI tool. It originated as Alibaba Group's internal official AI code review assistant — over the past two years, it has served tens of thousands of developers and identified millions of code defects. After thorough validation at massive scale, we incubated it into an open source project for the community. Simply configure a model endpoint to get started.
+
+It reads Git diffs, sends changed files to a configurable LLM via an agent with tool-use capabilities, and generates structured review comments with line-level precision. The agent can read full file contents, search the codebase, inspect other changed files for context, and produce deep reviews — not just surface-level diff feedback.
+
+![Highlights](imgs/highlights-en.png)
+
+## Why Open Code Review?
+
+### The Problem with General-Purpose Agents
+
+If you've used general-purpose agents like Claude Code with Skills for code review, you've likely encountered these pain points:
+
+- **Incomplete coverage** — On larger changesets, agents tend to "cut corners," selectively reviewing only some files and missing others.
+- **Position drift** — Reported issues frequently don't match the actual code location, with line numbers or file references drifting off target.
+- **Unstable quality** — Natural-language-driven Skills are hard to debug, and review quality fluctuates significantly with minor prompt variations.
+
+The root cause: a purely language-driven architecture lacks hard constraints on the review process.
+
+### Core Design: Deterministic Engineering × Agent Hybrid
+
+Open Code Review's core philosophy is to combine deterministic engineering with an agent, each handling what it does best.
+
+**Deterministic Engineering — Hard Constraints**
+
+For review steps that *must not go wrong*, engineering logic — not the language model — guarantees correctness:
+
+- **Precise file selection** — Determines exactly which files need review and which should be filtered, ensuring no important change is missed.
+- **Smart file bundling** — Groups related files into a single review unit (e.g., `message_en.properties` and `message_zh.properties` are bundled together). Each bundle runs as a sub-agent with isolated context — a divide-and-conquer strategy that stays stable on very large changesets and naturally supports concurrent review.
+- **Fine-grained rule matching** — Matches review rules to each file's characteristics, keeping the model's attention sharply focused and eliminating information noise at the source. Compared to purely language-driven rule guidance, template-engine-based rule matching is more stable and predictable.
+- **External positioning and reflection modules** — Independent comment-positioning and comment-reflection modules systematically improve both the location accuracy and content accuracy of AI feedback.
+
+**Agent — Dynamic Decision-Making**
+
+The agent's strengths are concentrated where they matter most — dynamic decisions and dynamic context retrieval:
+
+- **Scenario-tuned prompts** — Prompt templates deeply optimized for code review, improving effectiveness while reducing token consumption.
+- **Scenario-tuned toolset** — Distilled from deep analysis of tool-call traces in large-scale production data — including call frequency distributions, per-tool repetition rates, and the impact of new tools on the overall call chain — resulting in a purpose-built toolset that is more stable and predictable for code review than a generic agent toolkit.
+
+## How to Use
+
+### CLI
+
+#### Install
+
+**Via NPM (Recommended)**
 
 ```bash
 npm install -g @alibaba-group/open-code-review
@@ -10,86 +69,283 @@ npm install -g @alibaba-group/open-code-review
 
 After installation, the `ocr` command is available globally.
 
-### Version Control
+**From GitHub Release**
+
+Download the latest binary from [GitHub Releases](https://github.com/alibaba/open-code-review/releases):
 
 ```bash
-# Install specific version
-OCR_VERSION=v1.0.0 npm install -g @alibaba-group/open-code-review
-```
+# macOS (Apple Silicon)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
 
-## Prerequisites
+# macOS (Intel)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# Linux (x86_64)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# Linux (ARM64)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+```
 
-**You must configure an LLM provider before using `ocr`.** The tool requires access to an OpenAI-compatible API endpoint (OpenAI, Claude, local models, etc.).
+**From Source**
 
 ```bash
-ocr config set llm.url https://api.anthropic.com/v1/messages \
-    && ocr config set llm.auth_token {{your-api-key}} \
-    && ocr config set llm.model claude-opus-4-6 \
-    && ocr config set llm.use_anthropic true  \
-    && ocr config set language Chinese
+git clone https://github.com/alibaba/open-code-review.git
+cd open-code-review
+make build
+sudo cp dist/opencodereview /usr/local/bin/ocr
 ```
 
-Config is stored in `~/.opencodereview/config.json`.
+#### Quick Start
+
+**1. Configure LLM**
 
-Or via environment variables:
+**You must configure an LLM before reviewing code.**
 
 ```bash
+# Option A: Interactive config
+ocr config set llm.url https://api.anthropic.com/v1/messages
+ocr config set llm.auth_token your-api-key-here
+ocr config set llm.model claude-opus-4-6
+ocr config set llm.use_anthropic true
+
+# Option B: Environment variables (highest priority)
 export OCR_LLM_URL=https://api.anthropic.com/v1/messages
-export OCR_LLM_TOKEN=your-api-key
+export OCR_LLM_TOKEN=your-api-key-here
 export OCR_LLM_MODEL=claude-opus-4-6
+export OCR_USE_ANTHROPIC=true
 ```
 
-### Test Connectivity
+Config is stored in `~/.opencodereview/config.json`.
+
+It is also compatible with Claude Code environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) and parses `~/.zshrc` / `~/.bashrc` for those exports.
+
+**2. Test Connectivity**
 
 ```bash
 ocr llm test
 ```
 
-## Quick Start
-
-Navigate to any Git repository and run:
+**3. Review**
 
 ```bash
-# Review all workspace changes
+cd your-project
+
+# Workspace mode — review all staged, unstaged, and untracked changes
 ocr review
 
-# Review diff between two branches
+# Branch range — compare two refs
 ocr review --from main --to feature-branch
 
-# Review a single commit
+# Single commit
 ocr review --commit abc123
 ```
 
+### Integrate with Coding Agents
+
+OCR can be seamlessly integrated into AI coding agents as a slash command, enabling code review directly within your agent workflow.
+
+#### Option 1: Install as a Skill
+
+Use `npx` to install the OCR skill into your project:
+
+```bash
+npx skills add alibaba/open-code-review --skill open-code-review
+```
+
+This installs the `open-code-review` skill from the [skills registry](skills/open-code-review/SKILL.md), which teaches your coding agent how to invoke `ocr` for code review, classify issues by priority, and optionally apply fixes.
+
+#### Option 2: Install as a Claude Code Plugin
+
+For [Claude Code](https://docs.anthropic.com/en/docs/claude-code), install the command plugin through the following command in Claude Code:
+
+```bash
+/plugin marketplace add alibaba/open-code-review
+/plugin install open-code-review@open-code-review
+```
+
+This registers the `/open-code-review:review` slash command, which runs OCR and automatically filters and fixes issues.
+
+#### Option 3: Copy the Command File Directly
+
+For a quick setup without any package manager, simply copy the command file to use the `/open-code-review` slash command in Claude Code.
+
+**Project-level** (shared with team via git):
+
+```bash
+mkdir -p .claude/commands
+curl -o .claude/commands/open-code-review.md \
+  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
+```
+
+**User-level** (personal global use across all projects):
+
+```bash
+mkdir -p ~/.claude/commands
+curl -o ~/.claude/commands/open-code-review.md \
+  https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
+```
+
+> **Prerequisite**: All integration methods require the `ocr` CLI to be installed and an LLM configured. See [Install](#install) and [Configure LLM](#1-configure-llm) above.
+
+### CI/CD Integration
+
+OCR can be integrated into CI/CD pipelines to automate code review on Merge Requests / Pull Requests.
+
+The core command for CI integration:
+
+```bash
+ocr review \
+  --from "origin/main" \
+  --to "origin/feature-branch" \
+  --format json \
+  --audience agent
+```
+
+The `--format json` and `--audience agent` flags output machine-readable results suitable for parsing in CI scripts.
+
+See the [`examples/`](./examples/) directory for integration examples:
+
+- [`github_actions/`](./examples/github_actions/) — GitHub Actions integration example
+- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI integration example
+
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `ocr review` / `ocr r` | Start code review |
-| `ocr config set <key> <value>` | Manage configuration |
-| `ocr llm test` | Test LLM connectivity |
-| `ocr viewer` | Start WebUI session viewer |
-| `ocr version` | Show version info |
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `ocr review` | `ocr r` | Start a code review |
+| `ocr rules check <file>` | — | Preview which review rule applies to a file path |
+| `ocr config set <key> <value>` | — | Set configuration values |
+| `ocr llm test` | — | Test LLM connectivity |
+| `ocr viewer` | `ocr v` | Launch WebUI session viewer on `localhost:5483` |
+| `ocr version` | — | Show version info |
 
-## Common Options
+### `ocr review` Flags
 
 | Flag | Shorthand | Default | Description |
 |------|-----------|---------|-------------|
-| `--repo` | | current dir | Git repository root |
-| `--from` | | | Source ref (e.g., `main`) |
-| `--to` | | | Target ref (e.g., `feature-branch`) |
-| `--commit` | `-c` | | Review a single commit |
+| `--repo` | — | current dir | Git repository root |
+| `--from` | — | — | Source ref (e.g., `main`) |
+| `--to` | — | — | Target ref (e.g., `feature-branch`) |
+| `--commit` | `-c` | — | Single commit to review |
+| `--preview` | `-p` | `false` | Preview which files will be reviewed without running the LLM |
 | `--format` | `-f` | `text` | Output format: `text` or `json` |
-| `--concurrency` | | `4` | Max concurrent file reviews |
-| `--timeout` | | `10` | Per-file timeout (minutes) |
+| `--concurrency` | — | `8` | Max concurrent file reviews |
+| `--timeout` | — | `10` | Concurrent task timeout in minutes |
+| `--audience` | — | `human` | `human` (show progress) or `agent` (summary only) |
+| `--rule` | — | — | Path to custom JSON review rules |
+| `--tools` | — | — | Path to custom JSON tools config |
+
+## Examples
+
+```bash
+# Preview which files will be reviewed (no LLM calls)
+ocr review --preview
+ocr review -c abc123 -p
+
+# Review workspace changes with default settings
+ocr review
+
+# Review branch diff with higher concurrency
+ocr review --from main --to my-feature --concurrency 4
+
+# Review a specific commit with verbose JSON output
+ocr review --commit abc123 --format json --audience agent
+
+# Use custom review rules
+ocr review --rule /path/to/my-rules.json
+
+# Preview which rule applies to a file
+ocr rules check src/main/java/com/example/Foo.java
+ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml
+
+# View review session history in browser
+ocr viewer
+ocr viewer --addr :3000
+```
+
+## Review Rules
+
+OCR resolves review rules using a four-layer priority chain. Each layer uses first-match-wins: if a file path matches a pattern, that rule is used; otherwise it falls through to the next layer.
+
+| Priority | Source | Path | Description |
+|----------|--------|------|-------------|
+| 1 (highest) | `--rule` flag | User-specified path | CLI explicit override |
+| 2 | Project config | `<repoDir>/.opencodereview/rule.json` | Per-project rules, can be committed to git |
+| 3 | Global config | `~/.opencodereview/rule.json` | User-wide personal preferences |
+| 4 (lowest) | System default | Embedded `system_rules.json` | Built-in rules covering common languages and file types |
+
+### Rule File Format
+
+Layers 1–3 share the same JSON format:
+
+```json
+{
+  "rules": [
+    {
+      "path": "force-api/**/*.java",
+      "rule": "All new methods must validate required parameters for null values"
+    },
+    {
+      "path": "**/*mapper*.xml",
+      "rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
+    }
+  ]
+}
+```
+
+- `path` supports `**` recursive matching and `{java,kt}` brace expansion.
+- Within each layer, rules are evaluated in declaration order — the first match wins.
+- If a rule file does not exist, it is silently skipped.
+
+## Configuration Reference
+
+Config file: `~/.opencodereview/config.json`
+
+| Key | Type | Example |
+|-----|------|---------|
+| `llm.url` | string | `https://api.openai.com/v1/chat/completions` |
+| `llm.auth_token` | string | `sk-xxxxxxx` |
+| `llm.model` | string | `claude-opus-4-6` |
+| `llm.use_anthropic` | boolean | `true` \| `false` |
+| `language` | string | `English` \| `Chinese` (default: Chinese) |
+| `telemetry.enabled` | boolean | `true` \| `false` |
+| `telemetry.exporter` | string | `console` \| `otlp` |
+| `telemetry.otlp_endpoint` | string | OTLP collector address |
+| `telemetry.content_logging` | boolean | Include prompts in telemetry |
+
+Environment variables take precedence over the config file.
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `OCR_LLM_URL` | LLM API endpoint URL |
+| `OCR_LLM_TOKEN` | API key / auth token |
+| `OCR_LLM_MODEL` | Model name |
+| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI |
+
+
+## Telemetry
+
+OpenTelemetry integration for observability (spans, metrics). Disabled by default.
+
+```bash
+ocr config set telemetry.enabled true
+ocr config set telemetry.exporter otlp
+ocr config set telemetry.otlp_endpoint localhost:4317
+```
+
+Set `telemetry.content_logging` to include LLM prompts and responses in exported data.
 
-## Features
+## Contributing
 
-- **Three review modes**: workspace changes, branch range, single commit
-- **Context-aware**: Agent reads arbitrary files, searches code via `git grep`, inspects diffs
-- **Plan phase**: Large changes (>50 lines) get risk analysis first
-- **Any LLM**: Works with OpenAI, Claude-compatible endpoints, local models
-- **Concurrent**: Files reviewed in parallel (configurable workers)
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and how to submit pull requests.
 
 ## License
 
-Apache-2.0
+[Apache-2.0](LICENSE) — Copyright 2026 Alibaba

package/README.zh-CN.md

@@ -192,6 +192,27 @@ curl -o ~/.claude/commands/open-code-review.md \
 
 > **前置条件**：所有集成方式都需要安装 `ocr` CLI 并配置 LLM。参见上方[安装](#安装)和[配置 LLM](#1-配置-llm)。
 
+### CI/CD 集成
+
+OCR 可以集成到 CI/CD 流水线中，在 Merge Request / Pull Request 时自动进行代码审查。
+
+CI 集成的核心命令：
+
+```bash
+ocr review \
+  --from "origin/main" \
+  --to "origin/feature-branch" \
+  --format json \
+  --audience agent
+```
+
+`--format json` 和 `--audience agent` 参数输出适合 CI 脚本解析的机器可读结果。
+
+集成示例请参见 [`examples/`](./examples/) 目录：
+
+- [`github_actions/`](./examples/github_actions/) — GitHub Actions 集成示例
+- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI 集成示例
+
 ## 命令
 
 | 命令 | 别名 | 描述 |

package/examples/README.md

@@ -0,0 +1,10 @@
+# CI/CD Integration Examples
+
+This directory contains examples for integrating OpenCodeReview (OCR) into various CI/CD pipelines.
+
+## Contents
+
+- **[github_actions/](./github_actions/)** - GitHub Actions integration example
+- **[gitlab_ci/](./gitlab_ci/)** - GitLab CI integration example
+
+Each subdirectory contains its own README with detailed setup instructions.

package/examples/github_actions/README.md

@@ -0,0 +1,223 @@
+# OpenCodeReview - GitHub Actions Demo
+
+This demo shows how to integrate OpenCodeReview into your GitHub Actions workflow to automatically review Pull Requests and post review comments.
+
+## How It Works
+
+```
+PR Created/Updated → GitHub Actions Triggered → OCR Reviews Diff → Comments Posted on PR
+     OR
+Comment with trigger keyword ↗
+```
+
+1. When a PR is opened, synchronized, or reopened, the workflow triggers
+2. Alternatively, when a comment containing `/open-code-review` or `@open-code-review` is posted on a PR, the workflow triggers
+3. It installs OCR via `npm install -g @alibaba-group/open-code-review`
+4. Runs `ocr review --from origin/<base> --to origin/<head> --format json` to analyze the diff
+5. Parses the JSON output and posts inline review comments on the PR using GitHub's Pull Request Review API
+
+## Setup
+
+### 1. Copy the workflow file
+
+Copy `ocr-review.yml` to your repository's `.github/workflows/` directory:
+
+```bash
+mkdir -p .github/workflows
+cp ocr-review.yml .github/workflows/ocr-review.yml
+```
+
+### 2. Configure secrets
+
+Go to your repository's **Settings → Secrets and variables → Actions** and add:
+
+| Secret | Required | Description |
+|--------|----------|-------------|
+| `OCR_LLM_URL` | Yes | LLM API endpoint URL (e.g., `https://api.openai.com/v1/chat/completions`) |
+| `OCR_LLM_AUTH_TOKEN` | Yes | API authentication token |
+| `OCR_LLM_MODEL` | No | Model name (defaults to `gpt-4o`) |
+| `OCR_LLM_USE_ANTHROPIC` | No | Set to `true` if using Anthropic Claude models |
+
+> **Note:** `GITHUB_TOKEN` is automatically provided by GitHub Actions with the required `pull-requests: write` permission.
+>
+> The workflow also configures `llm.extra_body` to disable thinking mode for compatibility with various LLM providers.
+
+## Customization
+
+### Change the trigger events
+
+Modify the `on.pull_request.types` array in the workflow file:
+
+```yaml
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+```
+
+### Customize comment trigger keywords
+
+By default, the workflow triggers when a PR comment starts with `/open-code-review` or `@open-code-review`. You can customize these keywords by modifying the `if` condition in the workflow:
+
+```yaml
+if: |
+  github.event_name == 'pull_request' ||
+  (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/review')) ||
+  (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '@mybot'))
+```
+
+Or use a more flexible pattern with `contains` to trigger on any comment containing the keyword:
+
+```yaml
+if: |
+  github.event_name == 'pull_request' ||
+  (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '/review'))
+```
+
+> **Note:** The condition `github.event.issue.pull_request` ensures the comment is on a PR, not a regular issue.
+
+### Use a specific OCR version
+
+```yaml
+- name: Install OpenCodeReview
+  run: npm install -g @alibaba-group/open-code-review@1.0.0
+```
+
+### Add custom review rules
+
+Use the `--rule` flag to pass a custom rules JSON file:
+
+```yaml
+- name: Run OCR review
+  run: ocr review --rule ./my-rules.json --from origin/${{ github.base_ref }} --to origin/${{ github.head_ref }}
+```
+
+### Limit concurrency
+
+Adjust the `--concurrency` flag for large PRs to control the number of concurrent LLM requests:
+
+```yaml
+- name: Run OCR review
+  run: ocr review --concurrency 5 --from origin/${{ github.base_ref }} --to origin/${{ github.head_ref }}
+```
+
+### Provide background context
+
+Use the `--background` flag to pass additional context that helps OCR better understand the purpose of the changes:
+
+```yaml
+- name: Run OCR review
+  run: ocr review --background "${{ github.event.pull_request.title }}" --from origin/${{ github.base_ref }} --to origin/${{ github.head_ref }}
+```
+
+This is particularly useful when your PR titles follow semantic conventions (e.g., `feat(auth): add OAuth2 support`) that clearly summarize what the PR implements. The background information helps OCR provide more relevant and context-aware review comments.
+
+### Customize the review comment author with GitHub App
+
+By default, review comments are posted using the built-in `GITHUB_TOKEN`, which appears as `github-actions[bot]`. You can customize this by creating a GitHub App and using its credentials instead.
+
+For more details about GitHub Apps, see the [GitHub Apps documentation](https://docs.github.com/en/apps).
+
+#### Step 1: Create a GitHub App
+
+1. Go to your organization or personal account **Settings → Developer settings → GitHub Apps → New GitHub App**
+2. Fill in the following:
+   - **GitHub App name**: e.g., `OpenCodeReview Bot`
+   - **Homepage URL**: Your repository or documentation URL
+   - **Webhook**: Uncheck "Active" (not needed for this use case)
+3. Under **Repository permissions**, set:
+   - **Pull requests**: Read and write
+   - **Contents**: Read-only (for fetching diffs)
+   - **Metadata**: Read-only (required)
+4. Click **Create GitHub App**
+
+#### Step 2: Generate a Private Key
+
+1. After creating the app, scroll down to **Private keys**
+2. Click **Generate a private key**
+3. Download and save the `.pem` file securely
+
+Note your App ID from the app settings page.
+
+#### Step 3: Install the App
+
+1. In the left sidebar, click **Install App**
+2. Select the repositories where you want to use OCR
+3. After installation, note the **Installation ID** from the URL (e.g., `https://github.com/settings/installations/12345` → Installation ID is `12345`)
+
+#### Step 4: Configure Repository Secrets
+
+Add the following secrets to your repository (**Settings → Secrets and variables → Actions**):
+
+| Secret | Description |
+|--------|-------------|
+| `GITHUB_APP_ID` | Your GitHub App's ID |
+| `GITHUB_APP_PRIVATE_KEY` | Contents of the `.pem` file (including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`) |
+| `GITHUB_APP_INSTALLATION_ID` | The Installation ID from Step 3 |
+
+#### Step 5: Update the Workflow
+
+Add a step to obtain a token from the GitHub App, then use it in the "Post review comments to PR" step:
+
+```yaml
+- name: Get GitHub App Token
+  id: app-token
+  uses: actions/create-github-app-token@v1
+  with:
+    app-id: ${{ secrets.GITHUB_APP_ID }}
+    private-key: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}
+
+- name: Post review comments to PR
+  uses: actions/github-script@v7
+  with:
+    github-token: ${{ steps.app-token.outputs.token }}
+    script: |
+      # ... existing script
+```
+
+Now review comments will be posted with your custom GitHub App identity (e.g., `OpenCodeReview Bot`), providing a more professional and distinguishable appearance in your PRs.
+
+## Example Output
+
+When a PR is reviewed, comments appear directly in the PR's "Files changed" tab:
+
+- ✅ If no issues found: A comment saying "No comments generated. Looks good to me."
+- 🔍 If issues found: Inline review comments with suggestions using GitHub's native suggestion syntax
+
+### Inline Comment Example
+
+The workflow uses GitHub's `suggestion` code block syntax, so reviewers can apply fixes with one click:
+
+````markdown
+**Suggestion:**
+```suggestion
+// Fixed code here
+```
+````
+
+## Supported LLM Providers
+
+OCR supports both OpenAI and Anthropic API formats:
+
+- **OpenAI-compatible APIs** (default):
+  - OpenAI (GPT-4o, GPT-4, etc.)
+  - Azure OpenAI
+  - Self-hosted models (vLLM, Ollama, etc.)
+- **Anthropic APIs** (set `OCR_LLM_USE_ANTHROPIC: true`):
+  - Anthropic Claude models
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Failed to parse OCR output"**: Check that `OCR_LLM_URL` and `OCR_LLM_AUTH_TOKEN` secrets are correctly set
+2. **"Cannot find merge-base"**: Ensure `fetch-depth: 0` is set in the checkout step
+3. **Review comments not appearing on correct lines**: This can happen when the diff has changed since the review started; the workflow handles this gracefully with a fallback to issue comments
+
+### Debugging
+
+Enable debug logging by adding to the OCR review step:
+
+```yaml
+env:
+  OCR_DEBUG: "1"
+```