在 CI/CD 流水线中集成 OpenCodeReviewGitHub Actions 与 GitLab CI 全流程实战指南【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas 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-reviewOpenCodeReview以下简称 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_targetopened事件和正文以/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安装 OCRocr 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-reviewmain定义见仓库根目录的 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_progressfalse设为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-reviewmain 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 见评审规则文档。并发执行数默认每个文件组一个子 Agent8 个子 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-review1.0.0GitLab 配方还提供了通过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 writeContents: Read-only获取 diff 需要Metadata: Read-only必需在应用设置页生成私钥并下载.pem文件同时记下App ID。把应用安装到要评审的仓库。安装后 URL 中可见 Installation ID例如https://github.com/settings/installations/12345中的12345。在Settings → Secrets and variables → Actions中添加三个 SecretSecret值GITHUB_APP_IDApp ID。GITHUB_APP_PRIVATE_KEY.pem文件的完整内容含-----BEGIN RSA PRIVATE KEY-----与-----END RSA PRIVATE KEY-----行。GITHUB_APP_INSTALLATION_IDInstallation ID。在评论发布步骤签发令牌并使用- name: Get GitHub App Token id: app-token uses: actions/create-github-app-tokenv1 with: app-id: ${{ secrets.GITHUB_APP_ID }} private-key: ${{ secrets.GITHUB_APP_PRIVATE_KEY }} - name: Post review comments to PR uses: actions/github-scriptv7 with: github-token: ${{ steps.app-token.outputs.token }} script: | # ...沿用既有发布脚本...此后评审将以应用名义而不是github-actions[bot]发布。把结果上传到 GitHub Code ScanningSARIF--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-sarifv3 with: sarif_file: results.sarifSARIF 是机器可读格式因此 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 outputOCR_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 标签!-- ocr-… --、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-review1.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_page100 ) 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_URLGitLab 自动为所有运行器设置即可与自托管实例通信。只需确认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 403GITLAB_API_TOKEN缺少api作用域、不是项目成员或在自托管环境中使用了其他实例签发的令牌。请以api作用域重新签发并注册到Settings → CI/CD → Variables。Failed to parse OCR outputOCR_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.logGitLab 示例的发布脚本还有更完整的限流调优变量包括指数退避基数、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。相关文档CLI 参考——两套流水线消费的 JSON 输出结构自写 CI 脚本时必备。配置文档——OCR 识别的全部环境变量与配置键包括llm.extra_body、language、llm.auth_header等流水线中会用到的键。评审规则文档——--rule标志与规则解析优先级。综上GitHub Actions 与 GitLab CI 两套集成本质上都是触发事件 → 安装 OCR →ocr config set配置 → range 模式评审 → 解析 JSON → 平台 API 发布评论这条六步链路的封装。理解这条链路与两类凭证的边界再结合各平台的变量注入与身份机制你就能在自己的 CI 环境中稳定运行 LLM 驱动的行内代码评审并依据需要灵活定制触发条件、并发、规则与发布身份。【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考