@alibaba-group/open-code-review 1.2.5 → 1.3.0

package/README.ja-JP.md

@@ -117,27 +117,33 @@ sudo cp dist/opencodereview /usr/local/bin/ocr
 # オプションA: 対話的な設定
 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.auth_header x-api-key
 ocr config set llm.model claude-opus-4-6
 ocr config set llm.use_anthropic true
 
 # オプションB: 環境変数（最優先）
 export OCR_LLM_URL=https://api.anthropic.com/v1/messages
 export OCR_LLM_TOKEN=your-api-key-here
-export OCR_LLM_AUTH_HEADER=x-api-key
 export OCR_LLM_MODEL=claude-opus-4-6
 export OCR_USE_ANTHROPIC=true
 ```
 
 設定は`~/.opencodereview/config.json`に保存されます。
 
-Anthropicでは、標準の`sk-ant-*` APIキーは`x-api-key`を使用し、OAuthトークンは`authorization`を使用します。`llm.auth_header` / `OCR_LLM_AUTH_HEADER`を省略した場合、OCRは既存の`authorization` bearer-token動作を維持します。
+**`auth_header`（オプション）：** Anthropic使用時にAPIキーを送信するHTTPヘッダーを制御します。省略時のデフォルトは`authorization`（Bearerトークン）です。標準の`sk-ant-*` APIキーを使用する場合は、`x-api-key`に設定する必要があります：
+
+```bash
+ocr config set llm.auth_header x-api-key
+# または
+export OCR_LLM_AUTH_HEADER=x-api-key
+```
+
+サポートされる値：`x-api-key`、`authorization`（エイリアス：`bearer`）。それ以外の値はエラーになります。
 
 また、Claude Codeの環境変数（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`）とも互換性があり、`~/.zshrc` / `~/.bashrc`からこれらのexportをパースします。
 
 > **CC-Switchユーザー向けの注意**: [CC-Switch](https://github.com/farion1231/cc-switch)を[ルーティングサービス](https://www.ccswitch.io/en/docs?section=proxy&item=service)有効で使用している場合、追加設定なしで`llm.url`をCC-Switchのプロキシアドレスに向けることができます：
 > - **Claude**プロバイダーの場合: `llm.url`を`http://127.0.0.1:15721`に設定
-> - **CodeX**プロバイダーの場合: `llm.url`を`http://127.0.0.1:15721/v1`に設定
+> - **Codex**プロバイダーの場合: `llm.url`を`http://127.0.0.1:15721/v1`に設定
 > - `llm.model`はプロバイダー設定に応じて設定
 > - `llm.auth_token`は任意の値で構いません
 > - `extra_body`設定は引き続き有効です
@@ -290,6 +296,7 @@ ocr review \
 | `--concurrency` | — | `8` | ファイルレビューの最大同時実行数 |
 | `--timeout` | — | `10` | 同時実行タスクのタイムアウト（分） |
 | `--audience` | — | `human` | `human`（進捗を表示）または`agent`（サマリーのみ） |
+| `--background` | `-b` | — | レビューのための任意の要件/ビジネスコンテキスト。`--commit`使用時に未指定の場合、コミットメッセージから自動取得 |
 | `--rule` | — | — | カスタムJSONレビュールールへのパス |
 | `--max-tools` | — | 組み込み値 | ファイルごとのツール呼び出しラウンドの上限。テンプレートのデフォルトより大きい場合のみ有効 |
 | `--max-git-procs` | — | 組み込み値 | gitサブプロセスの最大同時実行数 |
@@ -311,6 +318,9 @@ ocr review --from main --to my-feature --concurrency 4
 # 特定のコミットを詳細なJSON出力でレビュー
 ocr review --commit abc123 --format json --audience agent
 
+# 要件コンテキストを提供してより的確なレビューを実施
+ocr review --background "ログインAPIにレート制限を追加"
+
 # カスタムレビュールールを使用
 ocr review --rule /path/to/my-rules.json
 

package/README.ko-KR.md

@@ -117,27 +117,33 @@ sudo cp dist/opencodereview /usr/local/bin/ocr
 # Option A: 대화형 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.auth_header x-api-key
 ocr config set llm.model claude-opus-4-6
 ocr config set llm.use_anthropic true
 
 # Option B: 환경 변수(가장 높은 우선순위)
 export OCR_LLM_URL=https://api.anthropic.com/v1/messages
 export OCR_LLM_TOKEN=your-api-key-here
-export OCR_LLM_AUTH_HEADER=x-api-key
 export OCR_LLM_MODEL=claude-opus-4-6
 export OCR_USE_ANTHROPIC=true
 ```
 
 config는 `~/.opencodereview/config.json`에 저장됩니다.
 
-Anthropic에서는 표준 `sk-ant-*` API key는 `x-api-key`를 사용하고, OAuth token은 `authorization`을 사용합니다. `llm.auth_header` / `OCR_LLM_AUTH_HEADER`를 생략하면 OCR은 기존 `authorization` bearer-token 동작을 유지합니다.
+**`auth_header` (선택사항):** Anthropic 사용 시 API key를 전송할 HTTP header를 제어합니다. 생략하면 기본값은 `authorization` (Bearer token)입니다. 표준 `sk-ant-*` API key를 사용하는 경우 `x-api-key`로 설정해야 합니다:
+
+```bash
+ocr config set llm.auth_header x-api-key
+# 또는
+export OCR_LLM_AUTH_HEADER=x-api-key
+```
+
+지원되는 값: `x-api-key`, `authorization` (별칭: `bearer`). 그 외 값은 오류로 처리됩니다.
 
 Claude Code 환경 변수(`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`)와도 호환되며, `~/.zshrc` / `~/.bashrc`의 export도 파싱합니다.
 
 > **CC-Switch 사용자 참고**: [CC-Switch](https://github.com/farion1231/cc-switch)를 [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service)와 함께 사용한다면, 추가 설정 없이 `llm.url`을 CC-Switch proxy 주소로 지정할 수 있습니다.
 > - **Claude** provider: `llm.url`을 `http://127.0.0.1:15721`로 설정
-> - **CodeX** provider: `llm.url`을 `http://127.0.0.1:15721/v1`로 설정
+> - **Codex** provider: `llm.url`을 `http://127.0.0.1:15721/v1`로 설정
 > - provider 설정에 맞게 `llm.model` 설정
 > - `llm.auth_token`은 아무 값이나 사용할 수 있음
 > - `extra_body` 설정은 그대로 적용됨
@@ -290,6 +296,7 @@ ocr review \
 | `--concurrency` | - | `8` | 최대 동시 파일 리뷰 수 |
 | `--timeout` | - | `10` | 동시 task timeout(분) |
 | `--audience` | - | `human` | `human`(progress 표시) 또는 `agent`(summary only) |
+| `--background` | `-b` | - | 리뷰를 위한 선택적 요구사항/비즈니스 컨텍스트. `--commit` 사용 시 미지정이면 commit message에서 자동 추출 |
 | `--rule` | - | - | custom JSON review rules 경로 |
 | `--max-tools` | - | built-in | 파일별 최대 tool call round. template default보다 클 때만 적용 |
 | `--max-git-procs` | - | built-in | 최대 동시 git subprocess 수 |
@@ -311,6 +318,9 @@ ocr review --from main --to my-feature --concurrency 4
 # 특정 commit을 verbose JSON output으로 리뷰
 ocr review --commit abc123 --format json --audience agent
 
+# 요구사항 컨텍스트를 제공하여 더 정확한 리뷰 수행
+ocr review --background "로그인 API에 rate limiting 추가"
+
 # custom review rules 사용
 ocr review --rule /path/to/my-rules.json
 

package/README.md

@@ -117,27 +117,33 @@ sudo cp dist/opencodereview /usr/local/bin/ocr
 # 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.auth_header x-api-key
 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-here
-export OCR_LLM_AUTH_HEADER=x-api-key
 export OCR_LLM_MODEL=claude-opus-4-6
 export OCR_USE_ANTHROPIC=true
 ```
 
 Config is stored in `~/.opencodereview/config.json`.
 
-For Anthropic, standard `sk-ant-*` API keys use `x-api-key`; OAuth tokens use `authorization`. If `llm.auth_header` / `OCR_LLM_AUTH_HEADER` is omitted, OCR keeps the existing `authorization` bearer-token behavior.
+**`auth_header` (optional):** Controls which HTTP header carries the API key when using Anthropic. Defaults to `authorization` (Bearer token) if omitted. If you use a standard `sk-ant-*` API key, you must set it to `x-api-key`:
+
+```bash
+ocr config set llm.auth_header x-api-key
+# or
+export OCR_LLM_AUTH_HEADER=x-api-key
+```
+
+Supported values: `x-api-key`, `authorization` (alias: `bearer`). Other values are rejected with an error.
 
 It is also compatible with Claude Code environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) and parses `~/.zshrc` / `~/.bashrc` for those exports.
 
 > **Note for CC-Switch Users**: If you are using [CC-Switch](https://github.com/farion1231/cc-switch) with [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service) enabled, you can point `llm.url` to the CC-Switch proxy address without additional configuration:
 > - For **Claude** provider: set `llm.url` to `http://127.0.0.1:15721`
-> - For **CodeX** provider: set `llm.url` to `http://127.0.0.1:15721/v1`
+> - For **Codex** provider: set `llm.url` to `http://127.0.0.1:15721/v1`
 > - Set `llm.model` according to your provider settings
 > - `llm.auth_token` can be any value
 > - `extra_body` settings still apply
@@ -255,10 +261,12 @@ The core command for CI integration:
 ```bash
 ocr review \
   --from "origin/main" \
-  --to "origin/feature-branch" \
+  --to "<commit_sha>" \
   --format json
 ```
 
+The `--from` flag accepts a branch ref (e.g., `origin/main`) or commit SHA as the base, while `--to` accepts a commit SHA or branch ref as the head. In CI environments, using commit SHA for `--to` is recommended to correctly handle fork PRs/MRs where the source branch doesn't exist on the origin remote.
+
 The `--format json` flag outputs machine-readable results suitable for parsing in CI scripts.
 
 See the [`examples/`](./examples/) directory for integration examples:
@@ -290,6 +298,7 @@ See the [`examples/`](./examples/) directory for integration examples:
 | `--concurrency` | — | `8` | Max concurrent file reviews |
 | `--timeout` | — | `10` | Concurrent task timeout in minutes |
 | `--audience` | — | `human` | `human` (show progress) or `agent` (summary only) |
+| `--background` | `-b` | — | Optional requirement/business context for the review; auto-filled from commit message when using `--commit` |
 | `--rule` | — | — | Path to custom JSON review rules |
 | `--max-tools` | — | built-in | Max tool call rounds per file; only takes effect when greater than template default |
 | `--max-git-procs` | — | built-in | Max concurrent git subprocesses |
@@ -311,6 +320,9 @@ 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
 
+# Provide requirement context for more targeted review
+ocr review --background "Adding rate limiting to the login API"
+
 # Use custom review rules
 ocr review --rule /path/to/my-rules.json
 

package/README.zh-CN.md

@@ -117,27 +117,33 @@ sudo cp dist/opencodereview /usr/local/bin/ocr
 # 方式 A：交互式配置
 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.auth_header x-api-key
 ocr config set llm.model claude-opus-4-6
 ocr config set llm.use_anthropic true
 
 # 方式 B：环境变量（优先级最高）
 export OCR_LLM_URL=https://api.anthropic.com/v1/messages
 export OCR_LLM_TOKEN=your-api-key-here
-export OCR_LLM_AUTH_HEADER=x-api-key
 export OCR_LLM_MODEL=claude-opus-4-6
 export OCR_USE_ANTHROPIC=true
 ```
 
 配置存储于 `~/.opencodereview/config.json`。
 
-对于 Anthropic，标准 `sk-ant-*` API key 使用 `x-api-key`；OAuth token 使用 `authorization`。如果未配置 `llm.auth_header` / `OCR_LLM_AUTH_HEADER`，OCR 会保留现有的 `authorization` bearer-token 行为。
+**`auth_header`（可选）：** 控制使用 Anthropic 时通过哪个 HTTP header 传递 API key。省略时默认为 `authorization`（Bearer token）。如果你使用标准 `sk-ant-*` API key，需要将其设为 `x-api-key`：
+
+```bash
+ocr config set llm.auth_header x-api-key
+# 或
+export OCR_LLM_AUTH_HEADER=x-api-key
+```
+
+支持的值：`x-api-key`、`authorization`（别名：`bearer`）。其他值会直接报错。
 
 同时兼容了 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。
 
 > **CC-Switch 用户特别提醒**：如果你使用 [CC-Switch](https://github.com/farion1231/cc-switch) 并开启了[路由服务](https://www.ccswitch.io/zh/docs?section=proxy&item=service)，可以将 `llm.url` 配置成 CC-Switch 启动的代理地址，无需额外配置：
 > - 如果路由的是 **Claude** 供应商：设置 `llm.url` 为 `http://127.0.0.1:15721`
-> - 如果路由的是 **CodeX** 供应商：设置 `llm.url` 为 `http://127.0.0.1:15721/v1`
+> - 如果路由的是 **Codex** 供应商：设置 `llm.url` 为 `http://127.0.0.1:15721/v1`
 > - `llm.model` 根据你的供应商设置进行配置
 > - `llm.auth_token` 可以设置成任意值
 > - `extra_body` 设置依然生效
@@ -290,6 +296,7 @@ ocr review \
 | `--concurrency` | — | `8` | 最大并发文件审查数 |
 | `--timeout` | — | `10` | 并发任务超时时间（分钟） |
 | `--audience` | — | `human` | `human`（显示进度）或 `agent`（仅输出摘要） |
+| `--background` | `-b` | — | 可选的需求/业务背景信息；使用 `--commit` 时如未指定则自动从 commit message 中提取 |
 | `--rule` | — | — | 自定义 JSON 审查规则路径 |
 | `--max-tools` | — | 内置默认 | 每个文件的最大工具调用轮次；仅在大于模板默认值时生效 |
 | `--max-git-procs` | — | 内置默认 | 最大并发 git 子进程数 |
@@ -311,6 +318,9 @@ ocr review --from main --to my-feature --concurrency 4
 # 审查特定提交并以 JSON 格式输出详细信息
 ocr review --commit abc123 --format json --audience agent
 
+# 提供需求背景以获得更有针对性的审查
+ocr review --background "为登录 API 添加限流"
+
 # 使用自定义审查规则
 ocr review --rule /path/to/my-rules.json
 

package/examples/github_actions/README.md

@@ -10,10 +10,10 @@ PR Created/Updated → GitHub Actions Triggered → OCR Reviews Diff → Comment
 Comment with trigger keyword ↗
 ```
 
-1. When a PR is opened, synchronized, or reopened, the workflow triggers
+1. When a PR is opened, the workflow triggers (uses `pull_request_target` for fork secret access)
 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
+4. Runs `ocr review --from origin/<base> --to <head_sha> --format json` to analyze the diff (uses commit SHA to support fork PRs)
 5. Parses the JSON output and posts inline review comments on the PR using GitHub's Pull Request Review API
 
 ## Setup
@@ -46,11 +46,11 @@ Go to your repository's **Settings → Secrets and variables → Actions** and a
 
 ### Change the trigger events
 
-Modify the `on.pull_request.types` array in the workflow file:
+Modify the `on.pull_request_target.types` array in the workflow file:
 
 ```yaml
 on:
-  pull_request:
+  pull_request_target:
     types: [opened, synchronize, reopened, ready_for_review]
 ```
 
@@ -60,7 +60,7 @@ By default, the workflow triggers when a PR comment starts with `/open-code-revi
 
 ```yaml
 if: |
-  github.event_name == 'pull_request' ||
+  github.event_name == 'pull_request_target' ||
   (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'))
 ```
@@ -69,7 +69,7 @@ Or use a more flexible pattern with `contains` to trigger on any comment contain
 
 ```yaml
 if: |
-  github.event_name == 'pull_request' ||
+  github.event_name == 'pull_request_target' ||
   (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '/review'))
 ```
 

package/examples/github_actions/ocr-review.yml

@@ -4,7 +4,7 @@
 # and posts review comments directly on the PR.
 #
 # Triggers:
-#   - PR opened, synchronized, or reopened
+#   - PR opened (uses pull_request_target for fork secret access)
 #   - Comment on PR containing '/open-code-review' or '@open-code-review'
 #
 # Required secrets:
@@ -18,8 +18,15 @@
 
 name: OpenCodeReview PR Review
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 on:
-  pull_request:
+  # Use pull_request_target instead of pull_request so that secrets are
+  # available even for PRs from forks. This is safe because OCR only reads
+  # the diff and does not execute any code from the PR.
+  pull_request_target:
     types: [opened]
   issue_comment:
     types: [created]
@@ -33,13 +40,13 @@ jobs:
     runs-on: ubuntu-latest
     # Run on PR events, or on comments starting with trigger keywords
     if: |
-      github.event_name == 'pull_request' ||
+      github.event_name == 'pull_request_target' ||
       (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/open-code-review')) ||
       (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '@open-code-review'))
     steps:
       - name: Get PR context
         id: pr-context
-        if: github.event_name != 'pull_request'
+        if: github.event_name != 'pull_request_target'
         uses: actions/github-script@v7
         with:
           script: |
@@ -58,7 +65,10 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0  # Full history needed for merge-base diff
-          ref: ${{ github.event_name != 'pull_request' && steps.pr-context.outputs.head_sha || '' }}
+          ref: ${{ github.event.pull_request.head.sha || steps.pr-context.outputs.head_sha }}
+
+      - name: Fetch PR head ref (ensures fork commits are available)
+        run: git fetch origin pull/${{ github.event.pull_request.number || github.event.issue.number }}/head
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -79,21 +89,23 @@ jobs:
       - name: Run OpenCodeReview
         id: review
         run: |
-          # Get base and head refs from PR context (different for comment triggers)
-          if [ "${{ github.event_name }}" = "pull_request" ]; then
+          # Get base ref and head SHA from PR context (different for comment triggers)
+          # Note: We use HEAD_SHA instead of origin/${HEAD_REF} to support fork PRs,
+          # because fork branches don't exist on the origin remote.
+          if [ "${{ github.event_name }}" = "pull_request_target" ]; then
             BASE_REF="${{ github.event.pull_request.base.ref }}"
-            HEAD_REF="${{ github.event.pull_request.head.ref }}"
+            HEAD_SHA="${{ github.event.pull_request.head.sha }}"
           else
             BASE_REF="${{ steps.pr-context.outputs.base_ref }}"
-            HEAD_REF="${{ steps.pr-context.outputs.head_ref }}"
+            HEAD_SHA="${{ steps.pr-context.outputs.head_sha }}"
           fi
 
-          echo "Reviewing PR: ${HEAD_REF} against ${BASE_REF}"
+          echo "Reviewing PR: ${HEAD_SHA} against origin/${BASE_REF}"
 
           # Run OCR in range mode with JSON output
           ocr review \
             --from "origin/${BASE_REF}" \
-            --to "origin/${HEAD_REF}" \
+            --to "${HEAD_SHA}" \
             --format json \
             > /tmp/ocr-result.json 2>/tmp/ocr-stderr.log || true
 
@@ -150,7 +162,7 @@ jobs:
             let commitSha;
             
             // Get commit SHA from event context
-            if (context.eventName === 'pull_request') {
+            if (context.eventName === 'pull_request_target') {
               commitSha = context.payload.pull_request.head.sha;
             } else {
               // For comment events, we need to fetch the PR

package/examples/gitlab_ci/.gitlab-ci.yml

@@ -2,20 +2,30 @@
 #
 # This pipeline automatically reviews Merge Requests using OpenCodeReview
 # and posts review comments (discussions) directly on the MR diff.
+# Supports both same-repo and forked MR scenarios.
 #
 # Required CI/CD Variables (Settings → CI/CD → Variables):
 #   OCR_LLM_URL        - LLM API endpoint (e.g., https://api.openai.com/v1/chat/completions)
 #   OCR_LLM_AUTH_TOKEN - Authentication token for the LLM API (mark as "Masked")
-#   GITLAB_API_TOKEN   - GitLab Personal/Project Access Token with "api" scope
 #
 # Optional CI/CD Variables:
 #   OCR_LLM_MODEL      - Model name (default: gpt-4o)
+#   GITLAB_API_TOKEN   - GitLab Personal/Project Access Token with "api" scope
+#                        (falls back to CI_JOB_TOKEN if not set)
+#
+# Fork MR Support:
+#   The script uses CI_COMMIT_SHA as the diff target to correctly resolve the
+#   source commit from forked repos. For some GitLab versions, you may need to enable:
+#   Project Settings → CI/CD → General pipelines →
+#     "Run pipelines in the parent project for merge requests from forked projects"
 
 stages:
   - review
 
 code-review:
   stage: review
+  interruptible: true
+  resource_group: mr-review-$CI_MERGE_REQUEST_IID
   image: node:20
   only:
     - merge_requests
@@ -27,7 +37,7 @@ code-review:
 
     # Configure OCR
     - mkdir -p ~/.open-code-review
-    # Gitlab CI/CD does not support setting variables with value length less than 8, so you can't set use_anthropic as a CI variable
+    # Gitlab CI/CD does not support configuring variables with value length less than 8, so you can't set use_anthropic as a CI variable
     - |
       ocr config set llm.url $OCR_LLM_URL
       ocr config set llm.auth_token $OCR_LLM_AUTH_TOKEN
@@ -35,13 +45,14 @@ code-review:
       ocr config set llm.use_anthropic false
       ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'
 
-    # Run OCR review
+    # Run OCR review (use CI_COMMIT_SHA for --to to support both same-repo and forked MRs)
     - |
       echo "Reviewing MR: ${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME} against ${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}"
       ocr review \
         --from "origin/${CI_MERGE_REQUEST_TARGET_BRANCH_NAME}" \
-        --to "origin/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}" \
+        --to "${CI_COMMIT_SHA}" \
         --format json \
+        --audience agent \
         > /tmp/ocr-result.json 2>/tmp/ocr-stderr.log || true
       echo "OCR review completed."
       cat /tmp/ocr-result.json
@@ -58,18 +69,27 @@ code-review:
       GITLAB_URL = os.environ.get("CI_SERVER_URL", "https://gitlab.com")
       PROJECT_ID = os.environ["CI_PROJECT_ID"]
       MR_IID = os.environ["CI_MERGE_REQUEST_IID"]
-      API_TOKEN = os.environ["GITLAB_API_TOKEN"]
+      # Fall back to CI_JOB_TOKEN for fork MR pipelines where GITLAB_API_TOKEN is unavailable
+      API_TOKEN = os.environ.get("GITLAB_API_TOKEN") or os.environ.get("CI_JOB_TOKEN", "")
       SOURCE_BRANCH = os.environ["CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]
       TARGET_BRANCH = os.environ["CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]
       COMMIT_SHA = os.environ["CI_COMMIT_SHA"]
 
+      if not API_TOKEN:
+          print("ERROR: No API token available (GITLAB_API_TOKEN or CI_JOB_TOKEN). Cannot post comments.", file=sys.stderr)
+          sys.exit(1)
+
       API_BASE = f"{GITLAB_URL}/api/v4/projects/{PROJECT_ID}/merge_requests/{MR_IID}"
 
+      # Determine auth header: PRIVATE-TOKEN for personal/project tokens, JOB-TOKEN for CI_JOB_TOKEN
+      USE_JOB_TOKEN = not os.environ.get("GITLAB_API_TOKEN")
+      AUTH_HEADER = "JOB-TOKEN" if USE_JOB_TOKEN else "PRIVATE-TOKEN"
+
       def api_request(endpoint, data=None, method="POST"):
           """Make a GitLab API request."""
           url = f"{API_BASE}{endpoint}"
           headers = {
-              "PRIVATE-TOKEN": API_TOKEN,
+              AUTH_HEADER: API_TOKEN,
               "Content-Type": "application/json"
           }
           body = json.dumps(data).encode("utf-8") if data else None
@@ -85,16 +105,16 @@ code-review:
           """Post a general note/comment on the MR."""
           return api_request("/notes", {"body": body})
 
-      def post_discussion(path, line, body, base_sha=None, start_sha=None, head_sha=None):
+      def post_discussion(path, line, body, base_sha, start_sha, head_sha):
           """Post an inline discussion on a specific file/line in the MR diff."""
           position = {
               "position_type": "text",
               "new_path": path,
               "old_path": path,
               "new_line": line,
-              "base_sha": base_sha or TARGET_BRANCH,
-              "start_sha": start_sha or TARGET_BRANCH,
-              "head_sha": head_sha or COMMIT_SHA,
+              "base_sha": base_sha,
+              "start_sha": start_sha,
+              "head_sha": head_sha,
           }
           data = {
               "body": body,
@@ -138,7 +158,7 @@ code-review:
 
       # --- Main ---
 
-      # Read OCR result
+      # Read OCR result (skip first line which is summary, not JSON)
       try:
           with open("/tmp/ocr-result.json", "r") as f:
               result = json.load(f)
@@ -168,7 +188,7 @@ code-review:
       diff_refs = None
       try:
           versions_url = f"{API_BASE}/versions"
-          req = urllib.request.Request(versions_url, headers={"PRIVATE-TOKEN": API_TOKEN})
+          req = urllib.request.Request(versions_url, headers={AUTH_HEADER: API_TOKEN})
           with urllib.request.urlopen(req) as resp:
               versions = json.loads(resp.read().decode("utf-8"))
           if versions:
@@ -191,15 +211,11 @@ code-review:
           start_line = comment.get("start_line", end_line)
           body = format_comment(comment)
 
-          if not path or not end_line:
+          if not path or not end_line or not diff_refs:
               failed_comments.append(comment)
               continue
 
-          kwargs = {}
-          if diff_refs:
-              kwargs = diff_refs
-
-          result_resp = post_discussion(path, end_line, body, **kwargs)
+          result_resp = post_discussion(path, end_line, body, **diff_refs)
           if result_resp:
               success_count += 1
           else:
@@ -214,8 +230,13 @@ code-review:
               fallback_body += format_comment_fallback(comment) + "\n\n---\n\n"
           post_note(fallback_body)
 
-      # Post summary
-      summary = f"🔍 **OpenCodeReview** found **{len(comments)}** issue(s) in this MR."
+      # Post summary last
+      total_count = len(comments)
+      failed_count = len(failed_comments)
+      summary = f"🔍 **OpenCodeReview** found **{total_count}** issue(s) in this MR."
+      if total_count > 0:
+          summary += f"\n- ✅ {success_count} posted as inline comment(s)"
+          summary += f"\n- 📝 {failed_count} posted as summary (missing line info)"
       if warnings:
           summary += f"\n\n⚠️ {len(warnings)} warning(s) occurred during review."
       post_note(summary)

package/examples/gitlab_ci/README.md

@@ -10,7 +10,7 @@ MR Created/Updated → GitLab Pipeline Triggered → OCR Reviews Diff → Discus
 
 1. When a Merge Request is opened or updated, the pipeline triggers
 2. It installs OCR via npm in a `node:20` Docker image
-3. Runs `ocr review --from origin/<target> --to origin/<source> --format json` to analyze the diff
+3. Runs `ocr review --from origin/<target> --to <commit_sha> --format json --audience agent` to analyze the diff (uses commit SHA to support fork MRs)
 4. Parses the JSON output and posts inline discussions on the MR using GitLab's Discussions API
 
 ## Setup
@@ -39,7 +39,7 @@ Go to your project's **Settings → CI/CD → Variables** and add:
 | `OCR_LLM_URL` | Yes | No | LLM API endpoint URL (e.g., `https://api.openai.com/v1/chat/completions`) |
 | `OCR_LLM_AUTH_TOKEN` | Yes | Yes | API authentication token |
 | `OCR_LLM_MODEL` | No | No | Model name (defaults to `gpt-4o`) |
-| `GITLAB_API_TOKEN` | Yes | Yes | GitLab access token with `api` scope |
+| `GITLAB_API_TOKEN` | No | Yes | GitLab access token with `api` scope (falls back to `CI_JOB_TOKEN` if not set) |
 
 > **Note:** GitLab CI/CD does not support variables with values shorter than 8 characters, so `use_anthropic` cannot be set as a CI variable. The pipeline sets it to `false` by default. If you need to use Anthropic Claude models, you'll need to modify the `.gitlab-ci.yml` script directly.
 >
@@ -53,7 +53,7 @@ You need a token with `api` scope to post discussions on MRs. Options:
 - **Personal Access Token**: User Settings → Access Tokens → Create with `api` scope
 - **Group Access Token**: For organization-wide usage
 
-> **Note:** The built-in `CI_JOB_TOKEN` does NOT have sufficient permissions to create MR discussions, which is why a separate token is needed.
+> **Note:** The built-in `CI_JOB_TOKEN` has limited API scope and may not support all discussion features (e.g., creating new threads on older GitLab versions). If `GITLAB_API_TOKEN` is not set, the pipeline falls back to `CI_JOB_TOKEN` automatically — but for best results, a dedicated token with `api` scope is recommended.
 >
 > **Tip:** For Project Access Tokens and Group Access Tokens, the token name determines the bot name shown in MR discussions. For example, naming your token `OpenCodeReview Bot` will make review comments appear as posted by `OpenCodeReview Bot`.
 
@@ -95,7 +95,7 @@ Use the `--rule` flag to pass a custom rules JSON file:
 
 ```yaml
 script:
-  - ocr review --rule ./my-rules.json --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to origin/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
+  - ocr review --rule ./my-rules.json --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to $CI_COMMIT_SHA
 ```
 
 ### Limit concurrency
@@ -104,7 +104,7 @@ Adjust the `--concurrency` flag for large MRs to control the number of concurren
 
 ```yaml
 script:
-  - ocr review --concurrency 5 --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to origin/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
+  - ocr review --concurrency 5 --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to $CI_COMMIT_SHA
 ```
 
 ### Provide background context
@@ -113,7 +113,7 @@ Use the `--background` flag to pass additional context that helps OCR better und
 
 ```yaml
 script:
-  - ocr review --background "$CI_MERGE_REQUEST_TITLE" --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to origin/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME
+  - ocr review --background "$CI_MERGE_REQUEST_TITLE" --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --to $CI_COMMIT_SHA
 ```
 
 This is particularly useful when your MR titles follow semantic conventions (e.g., `feat(auth): add OAuth2 support`) that clearly summarize what the MR implements. The background information helps OCR provide more relevant and context-aware review comments.
@@ -168,11 +168,13 @@ script:
 
     # No existing review found - run OCR
     print("🔍 No existing OCR review found. Running review...")
+    COMMIT_SHA = os.environ["CI_COMMIT_SHA"]
     result = subprocess.run([
         "ocr", "review",
         "--from", f"origin/{TARGET_BRANCH}",
-        "--to", f"origin/{SOURCE_BRANCH}",
-        "--format", "json"
+        "--to", COMMIT_SHA,
+        "--format", "json",
+        "--audience", "agent"
     ], capture_output=True, text=True)
 
     # Save output for the posting script

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alibaba-group/open-code-review",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "OpenCodeReview CLI — AI-powered code review tool",
   "bin": {
     "ocr": "bin/ocr.js"