在 CI/CD 流水线中集成 OpenCodeReview：GitHub Actions 与 GitLab CI 全流程实战指南-创锋一号

在 CI/CD 流水线中集成 OpenCodeReview：GitHub Actions 与 GitLab CI 全流程实战指南

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review

OpenCodeReview（以下简称 OCR）是一款混合架构的代码评审工具：它用确定性的规则管线（内置 NPE、线程安全、XSS、SQL 注入等多语言规则集）筛掉低价值内容，再交给 LLM Agent 产出精确到行号的评审意见。要让它在团队日常协作中真正跑起来，最自然的做法就是接入 CI/CD：为每一个 Pull Request / Merge Request 自动触发评审，并把结果以行内评论的形式回写到代码托管平台。本文以仓库中《CI/CD 集成文档》为主体，结合 GitHub Actions 示例工作流、复合动作定义、GitLab CI 示例与发布脚本，完整讲解两类流水线的原理、安装、配置、自定义与排障方法。读完你可以在自己的仓库中复制出一套可用的自动化代码评审流水线，并理解其内部每一环的工作原理。

CI/CD 集成是如何工作的

页面中的所有配方都遵循同一条流水线，GitHub Actions 与 GitLab CI 两套实现只是同一流程在不同平台上的落地。完整的流程分六步：

在 PR / MR 事件上触发。新的 pull request、更新的 merge request，或手动留下的/open-code-review评论都会启动一次任务。
在运行器上安装ocr。通常使用npm install -g @alibaba-group/open-code-review。CI 运行器是一次性的，因此每次执行时都需要重新安装。
用 CI 密钥配置 LLM。通过ocr config set指定端点、令牌和模型。运行器上不会残留可供依赖的~/.opencodereview配置文件，所有配置都来自 CI 平台注入的变量。
以 range 模式运行评审。以机器可读的格式输出，让 stdout 只包含干净的 JSON 响应：
```
ocr review \ --from "origin/<base-branch>" \ --to "origin/<head-branch>" \ --format json \ --audience agent
```
--format json产生可解析的负载，--audience agent抑制进度输出。所有配方消费的响应结构见 CLI 参考。
解析 JSON后遍历comments[]数组。
把评论发布到 PR / MR 上。使用各平台的原生 Review API。没有有效行号信息的条目（文件级意见）不以内联形式发布，而是汇总到摘要笔记中。当内联批量注册 API 拒绝请求时，发布阶段会降级为普通摘要评论。

两种凭证：LLM 凭证与 PR/MR 写令牌

整个流程中始终涉及两类凭证，容易混淆，需要明确区分：

LLM 凭证：OCR 生成意见时使用。对应OCR_LLM_URL、OCR_LLM_AUTH_TOKEN、OCR_LLM_MODEL等变量，最终通过ocr config set写入llm.*配置键。
PR/MR 写令牌：发布阶段在托管平台留评论时使用。GitHub 配方通过GITHUB_TOKEN自动获得（无需单独配置）；GitLab 推荐显式设置GITLAB_API_TOKEN，但在 fork MR 场景中内置的CI_JOB_TOKEN可作为替代（可以写入/discussions）。为了稳定可靠，官方明确推荐使用专用令牌。

一个值得注意的细节：CI 变量名是OCR_LLM_AUTH_TOKEN，但 OCR 真正直接读取的环境变量是OCR_LLM_TOKEN。文档与配置文档均明确指出这一映射关系，流水线内部正是通过ocr config set llm.auth_token_cmd 'printf "%s" "$OCR_LLM_TOKEN"'这类方式桥接的（见 action.yml）。排查认证问题时，先确认这一层转换是否生效。

GitHub Actions 集成

上游工作流位于 examples/github_actions/ocr-review.yml。

它做什么

示例工作流做了三件事：

触发条件：监听pull_request_target（opened事件）和正文以/open-code-review或@open-code-review开头的issue_comment事件。后者让评审者通过给 PR 留言即可触发 OCR 重新评审。之所以用pull_request_target而非pull_request，是为了让 fork 上发起的 PR 也能使用仓库 Secrets——OCR 只读取 diff、从不执行 PR 中的代码，因此这是安全的。
安装与配置：npm install -g @alibaba-group/open-code-review安装 OCR，ocr config set记录配置，然后以分支 range 模式执行核心命令。
发布评论：解析 JSON 响应，把每条意见通过 GitHub Pull Request Review API 发布为行内评审评论；无行号信息的评论汇总到摘要正文；批量注册失败时降级为逐条发布，并留下统计摘要评论。

值得注意的是工作流还包含一套条件并发组逻辑（见 ocr-review.yml）：匹配事件（PR 事件 +/open-code-review评论）共享按 PR 分组的并发组，新的评审会取消同 PR 的旧评审；不匹配的评论落入noop-<run_id>唯一分组，被立即跳过而不会干扰正在运行的评审。同时issue_comment触发被author_association限定为 MEMBER/OWNER/COLLABORATOR，避免任意人通过评论消耗团队的 LLM 配额。

安装

把工作流文件放入仓库：

mkdir -p .github/workflows curl -o .github/workflows/ocr-review.yml \ https://raw.githubusercontent.com/alibaba/open-code-review/main/examples/github_actions/ocr-review.yml

仓库内对应文件可直接参考 examples/github_actions/ocr-review.yml 对照修改。

必需的 Secrets

在Settings → Secrets and variables → Actions中配置：

Secret	必填	说明
`OCR_LLM_URL`	是	LLM API 端点（例如`https://api.openai.com/v1/chat/completions`）。
`OCR_LLM_AUTH_TOKEN`	是	LLM API 认证令牌。该 CI Secret 会传入`ocr config set llm.auth_token`。（OCR 直接读取的环境变量不是`OCR_LLM_AUTH_TOKEN`，而是`OCR_LLM_TOKEN`。）
`OCR_LLM_MODEL`	否	模型名称。没有默认值，必须显式指定，否则运行会失败。
`OCR_LLM_USE_ANTHROPIC`	否	使用 Anthropic Claude 模型时设为`true`。

GITHUB_TOKEN由平台自动提供，工作流已声明pull-requests: write权限以便发布评审评论。

关于 thinking 模式的说明：工作流在启动时会额外执行ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'。这是为了兼容不支持该字段的 LLM 提供商而关闭 thinking 模式请求。如果你使用的提供商需要保持 thinking 模式开启，请删除这行配置。该配置通过llm.extra_body合并进每一次请求，相关机制见配置文档中"发送供应商特定字段"一节。

动作输入（Action Inputs）

上游工作流把评审委托给可复用的复合动作uses: alibaba/open-code-review@main（定义见仓库根目录的 action.yml）。除上述凭证外，还可以通过动作步骤的with:传入以下输入来调整评审行为：

输入	默认值	说明
`effort`	`''`	传入`ocr review --effort`的评审强度预设：`low`、`medium`、`high`（大小写不敏感）。留空则遵循 CLI 默认值（已配置的值，否则为 medium）。需要 OCR v1.10.0 及以上版本，更低版本下动作会以明确错误提前失败。
`max_tokens_budget`	`''`	传入`ocr review --max-tokens-budget`的总令牌（输入 + 输出）上限。空或`'0'`表示无限。超限后分派停止，跳过的文件以`failed(budget)`报告，部分结果仍会照常发布，评审以 0 退出。
`llm_reasoning_effort`	`''`	支持`reasoning_effort`请求字段的模型（如 GLM-5.x、OpenAI reasoning 模型）的推理深度：`minimal`、`low`、`medium`、`high`、`max`（大小写不敏感）。通过`llm_extra_body`合并进请求体，因此对已发布的所有 CLI 版本都生效。`llm_extra_body`中显式的`reasoning_effort`键优先于此输入。留空（默认）则不发送任何内容。仅适用于 OpenAI 兼容协议——Anthropic API 会拒绝未知的请求体字段，因此在该协议下动作会立即失败。Anthropic 的 thinking 控制请使用`llm_extra_body`的显式键。
`stream_progress`	`'false'`	设为`'true'`时，不再静默等待执行结束，而是把`[ocr]`进度行实时输出到工作流日志（stderr 的 human audience）。这只是显示开关，stderr 仍会被捕获到文件中供产物与评论发布使用。

完整输入列表见 action.yml，涵盖发布模式（sticky_summary、incremental）、严重度/类别路由、跨推送检查点（checkpoint_range）等。复合动作内部会校验effort、max_tokens_budget、llm_reasoning_effort的取值与 OCR 最低版本，并在安装后解析实际版本用于配置指纹，确保检查点语义不被悄悄破坏。

结合示例的典型用法：

- uses: alibaba/open-code-review@main with: llm_url: ${{ secrets.OCR_LLM_URL }} llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} llm_model: ${{ vars.OCR_LLM_MODEL }} llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} effort: high max_tokens_budget: '10000000' llm_reasoning_effort: low stream_progress: 'true'

自定义

以下内容都是对刚复制的工作流文件（.github/workflows/ocr-review.yml）的修改方法。

背景上下文

--background是杠杆效应最大的参数（见 CLI 参考中的通用建议）。把 PR 标题传进去即可——当标题遵循语义化规范（如feat(auth): add OAuth2 support）时效果尤其好：

- name: Run OCR review env: PR_TITLE: ${{ github.event.pull_request.title }} BASE_REF: ${{ github.base_ref }} HEAD_REF: ${{ github.head_ref }} run: | ocr review \ --background "$PR_TITLE" \ --from "origin/$BASE_REF" \ --to "origin/$HEAD_REF" \ --format json --audience agent

安全提示：PR 中可控制的值不要直接以${{ }}内联进run:，而应通过env:传递。GitHub 在 shell 解析行之前就把${{ }}作为文本替换，因此含 shell 元字符的 PR 标题或分支名可能在运行器上被执行。

自定义规则

用--rule传入项目专属规则文件：

- name: Run OCR review env: BASE_REF: ${{ github.base_ref }} HEAD_REF: ${{ github.head_ref }} run: | ocr review --rule ./my-rules.json \ --from "origin/$BASE_REF" \ --to "origin/$HEAD_REF"

规则文件的 schema 见评审规则文档。

并发执行数

默认每个文件组一个子 Agent，8 个子 Agent 并行。大 PR 中若担心超出 LLM 提供商的请求限制，可以调低：

- name: Run OCR review env: BASE_REF: ${{ github.base_ref }} HEAD_REF: ${{ github.head_ref }} run: | ocr review --concurrency 5 \ --from "origin/$BASE_REF" \ --to "origin/$HEAD_REF"

--concurrency的 CLI 默认值正是 8，语义为"并行评审的最大文件组数"（见 cli-reference.md）。

触发条件

默认工作流在 PRopened和以/open-code-review或@open-code-review开头的 PR 评论上触发。常见调整有两类。

在更多 PR 生命周期事件上运行（例如新提交推送后重新评审）：

on: pull_request: types: [opened, synchronize, reopened, ready_for_review]

改用其他评论关键字：

if: | github.event_name == 'pull_request' || (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/review'))

github.event.issue.pull_request检查确保该评论属于 PR 而非普通 Issue。

固定 OCR 版本

默认工作流安装最近发布的版本。要固定版本：

- name: Install OpenCodeReview run: npm install -g @alibaba-group/open-code-review@1.0.0

（GitLab 配方还提供了通过OCR_VERSION变量固定版本的方案，详见后文。）

以 GitHub App 身份发布

默认评审评论以github-actions[bot]名义发布。要改为OpenCodeReview Bot之类的品牌机器人名义，需用 GitHub App 安装令牌替代GITHUB_TOKEN：

在Settings → Developer settings → GitHub Apps → New GitHub App创建应用。本用途不需要 Webhook，直接关闭。在Repository permissions中授予：
- Pull requests: Read and write
- Contents: Read-only（获取 diff 需要）
- Metadata: Read-only（必需）
在应用设置页生成私钥并下载.pem文件，同时记下App ID。
把应用安装到要评审的仓库。安装后 URL 中可见 Installation ID，例如https://github.com/settings/installations/12345中的12345。
在Settings → Secrets and variables → Actions中添加三个 Secret：
Secret 值
GITHUB_APP_ID App ID。
GITHUB_APP_PRIVATE_KEY .pem文件的完整内容，含-----BEGIN RSA PRIVATE KEY-----与-----END RSA PRIVATE KEY-----行。
GITHUB_APP_INSTALLATION_ID Installation ID。

Secret	值
`GITHUB_APP_ID`	App ID。
`GITHUB_APP_PRIVATE_KEY`	`.pem`文件的完整内容，含`-----BEGIN RSA PRIVATE KEY-----`与`-----END RSA PRIVATE KEY-----`行。
`GITHUB_APP_INSTALLATION_ID`	Installation ID。

在评论发布步骤签发令牌并使用：

- 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: | # ...沿用既有发布脚本...

此后评审将以应用名义而不是github-actions[bot]发布。

把结果上传到 GitHub Code Scanning（SARIF）

--format sarif向 stdout 输出 SARIF 2.1.0 报告。存为文件后用 CodeQL 的upload-sarif动作上传，结果会出现在Security → Code scanning中：

- name: Run OCR review env: BASE_REF: ${{ github.base_ref }} HEAD_REF: ${{ github.head_ref }} run: | ocr review \ --from "origin/$BASE_REF" \ --to "origin/$HEAD_REF" \ --format sarif --audience agent > results.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif

SARIF 是机器可读格式，因此 OCR 不会向 stdout 输出进度，results.sarif只包含报告。注意--preview不支持--format sarif——要生成报告需运行完整评审，或改用ocr scan。SARIF 输出的底层实现可参考 cmd/opencodereview/sarif.go。

故障排查

症状	原因 / 解决
`Cannot find merge-base`	检出步骤使用了 shallow clone，而 range 模式评审需要完整历史。上游工作流在`actions/checkout`中设置了`fetch-depth: 0`，修改文件时请保留该设置。
`Failed to parse OCR output`	`OCR_LLM_URL`或`OCR_LLM_AUTH_TOKEN`缺失或错误。到Settings → Secrets and variables → Actions复查取值。
评审评论落在错误的行	通常是评审开始到评论发布之间 diff 发生了位移。发布脚本会降级为普通 Issue 评论，无需额外处理。

注意：OCR_DEBUG环境变量尚未实现。设置OCR_DEBUG: "1"不会产生任何效果（文档特意记录以免后人误用）。现在要查看详细输出，可检查工作流在/tmp/ocr-result.json与/tmp/ocr-stderr.log留下的原始评审 JSON 和 stderr（相关产物上传逻辑见 action.yml），或在本地直接运行ocr review。

GitLab CI 集成

上游流水线位于examples/gitlab_ci/.gitlab-ci.yml（在本仓库中，该示例以 examples/gitlab_ci/README.md 与发布脚本 examples/gitlab_ci/post_review.py 的形式提供，README 内含完整流水线 YAML 与变量说明）。

它做什么

在merge_requests事件上触发（创建、更新、重开等所有 MR 事件）。
在node:20镜像中运行：安装 OCR、用ocr config set配置、以 MR diff 模式执行核心命令。
用内联 Python 脚本解析 JSON 响应，把每条意见通过 GitLab 讨论（diff 上的行内评论）发布。为精确定位，脚本通过 MR 的versions端点计算正确的base_sha/start_sha/head_sha。无法行内发布的评论降级为普通 MR 笔记，最后留下摘要笔记。

发布脚本 post_review.py 是纯标准库实现（仅依赖json与urllib），可在任意官方 python3 镜像上运行。它把与传输无关的publish流程与 GitLab REST 传输层GitLabPoster分离，从而可以在无网络、无真实延时的条件下进行单元测试（对应 post_review_test.py）。脚本行为与 GitHub 动作侧的post-review-comments.js对齐：每条评论带[category · severity]徽标、发布前确定性排序、粘性摘要（跨运行原地更新）、增量模式（跳过与既有机器人讨论重叠的行区间）、幂等重试（每条评论内嵌不可见 HTML 注释 id 标签）、400 行解析降级、限流等待与指数退避等。

安装

把流水线文件放到仓库根目录：

curl -o .gitlab-ci.yml \ https://raw.githubusercontent.com/alibaba/open-code-review/main/examples/gitlab_ci/.gitlab-ci.yml

若已有.gitlab-ci.yml且希望保留，可把配方放到其他路径并用include:引入：

include: - local: 'ci/ocr-review.gitlab-ci.yml'

必需的 CI/CD 变量

在Settings → CI/CD → Variables中配置：

变量	必填	掩码	说明
`OCR_LLM_URL`	是	否	LLM API 端点 URL。
`OCR_LLM_AUTH_TOKEN`	是	是	API 认证令牌。该 CI 变量会传入`ocr config set llm.auth_token`。（OCR 直接读取的环境变量是`OCR_LLM_TOKEN`，不是`OCR_LLM_AUTH_TOKEN`。）
`OCR_LLM_MODEL`	否	否	模型名称。没有默认值，必须显式指定。
`GITLAB_API_TOKEN`	否	是	带`api`作用域的 Project / Personal / Group Access Token。缺失时回退到内置`CI_JOB_TOKEN`（如 fork MR 场景）。为稳定可靠，推荐使用专用`GITLAB_API_TOKEN`。

GitLab 的 8 字符限制：GitLab 拒绝值短于 8 个字符的变量，因此流水线把llm.use_anthropic硬编码为false。要使用 Anthropic Claude 模型，需要直接修改脚本。
thinking 模式：流水线启动时同样执行ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'，用于兼容不支持该字段的提供商；需要保持 thinking 模式时删除该行即可。
机器人命名的快捷技巧：Project Access Token 与 Group Access Token 的名称会显示在 MR 讨论旁。把令牌命名为OpenCodeReview Bot即可不额外配置就给评审者身份加上品牌；只有当需要更稳健的服务账号方案时，才按后文"服务账号身份"配置。

自定义

以下内容都是对刚复制的.gitlab-ci.yml的修改方法。

背景上下文

把 MR 标题传给--background，标题遵循语义化规范时效果尤佳：

script: - | ocr review \ --background "$CI_MERGE_REQUEST_TITLE" \ --from "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" \ --to "${CI_COMMIT_SHA}" \ --format json --audience agent

注意这里--to使用 commit SHA 而非分支名，这是为了支持 fork MR 场景。

自定义规则与并发数

与 GitHub Actions 配方使用相同参数：项目专属规则文件用--rule，并行子 Agent 数（默认 8）用--concurrency调整：

script: - | ocr review --rule ./my-rules.json --concurrency 5 \ --from "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" \ --to "${CI_COMMIT_SHA}"

规则 schema 见评审规则文档。此外，GitLab 示例还支持通过 CI/CD 变量免改 YAML 完成多数调优：OCR_VERSION固定版本、OCR_LANGUAGE设置评论语言、OCR_LLM_AUTH_HEADER/OCR_LLM_EXTRA_HEADERS定制认证头、OCR_LLM_TIMEOUT设置超时、OCR_REVIEW_CONCURRENCY调并发、OCR_BACKGROUND传背景、OCR_RULE指定规则文件等（完整表格见 examples/gitlab_ci/README.md）。

固定 OCR 版本

script: - npm install -g @alibaba-group/open-code-review@1.0.0

避免每次 push 都重新评审

only: [merge_requests]会在所有MR 更新时触发，长期开放的 MR 会消耗大量 LLM 令牌。GitLab 没有"仅创建时"这类事件，官方推荐的做法是：运行评审前先检查是否已存在 OCR 笔记，存在则直接退出。把ocr review调用替换为以下 Python 包装器：

import json, os, sys, urllib.request 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"] url = ( f"{GITLAB_URL}/api/v4/projects/{PROJECT_ID}" f"/merge_requests/{MR_IID}/notes?per_page=100" ) req = urllib.request.Request(url, headers={"PRIVATE-TOKEN": API_TOKEN}) with urllib.request.urlopen(req) as resp: notes = json.loads(resp.read().decode()) if any("OpenCodeReview" in n.get("body", "") for n in notes): print("OCR already reviewed this MR. Skipping to save tokens.") sys.exit(0) # ...笔记不存在时照常调用 `ocr review ...`，并把 JSON 写入发布阶段期望的文件。

此后若想强制重新评审，删除 MR 上既有的 OCR 笔记即可；下次流水线运行看不到 OCR 笔记便会重新评审。

自托管 GitLab

无需修改代码。发布脚本读取CI_SERVER_URL（GitLab 自动为所有运行器设置），即可与自托管实例通信。只需确认GITLAB_API_TOKEN是在自托管实例而非gitlab.com上签发的。

以服务账号身份发布

默认评审讨论以GITLAB_API_TOKEN持有者的用户名发布。要以品牌机器人名义发布，需换成项目级服务账号：

在Project → Settings → Service Accounts → New service account创建服务账号，这里的名称（如OpenCodeReview Bot）会显示在 MR 讨论旁。
在Settings → Members → Invite member中邀请进项目：按名称搜索并授予Developer或Maintainer（两者都有写讨论的权限）。
在Settings → Service Accounts →（对应账号）→ Add new token中签发访问令牌，必需作用域为api。GitLab 只会展示一次令牌，请立即复制。
在Settings → CI/CD → Variables中替换令牌值：把既有GITLAB_API_TOKEN的值换成服务账号令牌，变量名保持不变。

此后讨论将以服务账号名义（而非原令牌创建者）发布。

故障排查

症状	原因 / 解决
`Cannot find merge-base`	运行器使用了 shallow clone。上游流水线通过`GIT_DEPTH: 0`强制完整克隆，修改文件时请保留。
发布时`API error 403`	`GITLAB_API_TOKEN`缺少`api`作用域、不是项目成员，或在自托管环境中使用了其他实例签发的令牌。请以`api`作用域重新签发并注册到Settings → CI/CD → Variables。
`Failed to parse OCR output`	`OCR_LLM_URL`或`OCR_LLM_AUTH_TOKEN`配置错误。到Settings → CI/CD → Variables复查。
行内评论落在错误的行	GitLab 要求行内讨论精确匹配 SHA，发布脚本会拉取`versions`元数据计算正确的`base_sha`/`start_sha`/`head_sha`。仍无法定位的意见会降级为普通 MR 笔记。

流水线把原始评审 JSON 留在/tmp/ocr-result.json、stderr 留在/tmp/ocr-stderr.log。要查看 OCR 究竟返回了什么，可在调试步骤输出这两个文件：

script: - cat /tmp/ocr-result.json - cat /tmp/ocr-stderr.log

（GitLab 示例的发布脚本还有更完整的限流调优变量，包括指数退避基数、Retry-After支持、RateLimit-Remaining主动节流、OCR_STICKY_SUMMARY、OCR_INCREMENTAL、OCR_ROUTE_SEVERITY_BELOW/OCR_ROUTE_CATEGORIES路由、OCR_FAIL_ON_SEVERITY失败门禁等，完整表格见 examples/gitlab_ci/README.md。）

企业官网建设流程全解析