在 GitHub Actions 与 GitLab CI 中接入 open-code-reviewPR/MR 自动代码审查完整实战指南【免费下载链接】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本指南基于 open-code-review 仓库中现成的 CI/CD 集成模板examples/github_actions/ocr-review.yml与examples/gitlab_ci/.gitlab-ci.yml系统讲解如何为每一个 Pull RequestPR或 Merge RequestMR自动运行 LLM 代码审查。读完本文你将掌握 CI 触发事件设计、LLM 与平台凭据的配置、ocr review区间审查与 JSON 输出的底层原理、评论回帖与故障排查的完整方法论并具备按需定制背景上下文、自定义规则、并行度、SARIF 上传、机器人身份发布等的实战能力。CI/CD 集成的工作原理无论使用哪个 CI 平台所有集成模板都遵循同一条六步流水线。GitHub Actions 与 GitLab CI 两个小节分别是这条通用模式的两种具体实现。事件触发新建 PR、更新 MR或人工在 PR 评论中输入/open-code-review触发审查。安装ocr在临时 runner 上通过npm install -g alibaba-group/open-code-review安装 CLI。由于 runner 每次都是全新的因此安装动作每次运行都会执行。配置 LLM从 CI 机密中读取端点、令牌、模型通过ocr config set写入配置。runner 上不存在可复用的~/.opencodereview配置文件作为兜底因此每次运行都必须显式完成配置。区间模式审查 机器可读输出以 stdout 输出纯净 JSON 为目标运行审查ocr review \ --from origin/base-branch \ --to origin/head-branch \ --format json \ --audience agent--format json提供可解析的数据结构--audience agent抑制进度行保证 stdout 是单一可解析文档。解析 JSON遍历结果中的comments[]数组。发布评论通过代码托管平台 API 将评论回写 PR/MR。没有合法行号信息的记录文件级意见会落入最终汇总评论若批量发布 API 拒绝请求发布阶段同样回退为普通汇总评论。整个过程始终涉及两类凭据其一是LLM 凭据用于让 OCR 生成意见其二是PR/MR 写入令牌用于让发布阶段回贴评论。GitHub 模板中第二个令牌由GITHUB_TOKEN免费提供GitLab 推荐显式配置GITLAB_API_TOKEN但 fork 仓库的 MR 可以用内置CI_JOB_TOKEN可通过/discussions发布讨论作为兜底——出于可靠性官方仍建议使用独立令牌。GitHub Actions 集成工作流做了什么标准工作流examples/github_actions/ocr-review.yml具备以下能力双重触发同时监听pull_request_targetopened/synchronize/reopened与issue_comment评论以/open-code-review或open-code-review开头。后者让审查者只需在 PR 内留言即可按需重新审查。之所以用pull_request_target而非pull_request是为了让 fork 仓库的 PR 也能读取到 secrets这是安全的因为 OCR 只读取 diff从不执行 PR 中的代码。安装与配置执行npm install -g alibaba-group/open-code-review用ocr config set写入配置随后以分支区间模式运行主命令。评论发布解析 JSON 对象通过 GitHub Pull Request Review API 将每条意见发布为行内审查评论无行号信息的意见进入汇总文本批量发布失败时逐条发布并输出统计信息到汇总评论。安全护栏issue_comment触发还进一步限定了author_association仅MEMBER/OWNER/COLLABORATOR且排除 Bot 账号避免任何人对 LLM 额度的滥用concurrency分组保证同一 PR 的新审查会取消陈旧审查而无关联的普通评论落入noop-run_id独立分组不会干扰进行中的审查。安装将工作流放入仓库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必需 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_TOKEN不是OCR_LLM_AUTH_TOKEN。OCR_LLM_MODEL否模型名。OCR 没有内置默认模型必须显式指定。OCR_LLM_USE_ANTHROPIC否使用 Anthropic Claude 模型时设为true。GITHUB_TOKEN由平台自动提供工作流声明了pull-requests: write权限用于发布审查评论对应ocr-review.yml中的permissions段。运行工作流时还会执行ocr config set llm.extra_body {thinking: {type: disabled}}为兼容不支持该字段的 LLM 提供商而关闭思考模式请求。若你的提供商要求开启思考模式请删除这一行。Action 参数详解工作流通过uses: alibaba/open-code-reviewmain将审查委托给仓库根目录的可复用复合 Actionaction.yml。除上述凭据外以下输入参数直接控制审查行为在with:中传入参数默认值说明effort审查强度预设透传给ocr review --effortlow、medium或high不区分大小写。空值保留 CLI 默认值已配置值或 medium。需要 OCR v1.10.0 及以上旧版本 action 会以明确错误提前退出。max_tokens_budget总令牌上限输入输出透传给ocr review --max-tokens-budget。空值或0表示无限制。超过上限后调度停止被跳过的文件标记为failed(budget)部分结果仍会发布审查以退出码 0 结束。llm_reasoning_effort对支持reasoning_effort请求字段的模型如 GLM-5.x、OpenAI 推理模型的推理深度minimal、low、medium、high、max不区分大小写。该值通过llm_extra_body注入请求体因此兼容所有已发布 CLI 版本llm_extra_body中显式的reasoning_effort键优先于此参数。空值默认不发送任何内容。仅支持 OpenAI 兼容协议——Anthropic API 会拒绝未知请求体字段因此在该协议下 action 立即失败Anthropic 的思考模式请通过llm_extra_body显式键管理。stream_progressfalse设为true时把[ocr]实时进度行human audience输出到 stderr流式显示到工作流日志而不是静默到运行结束。仅影响显示stderr 仍会写入文件用于制品与评论发布。- 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完整参数清单请查阅action.yml——包括发布模式sticky_summary粘性汇总、incremental增量去重、按严重级别/类别路由评论route_severity_below、route_categories、跨推送检查点checkpoint_range、full_review、评论批量大小review_comment_batch_size默认 50避免单次请求超出 GitHub 实际限制以及language、llm_timeout、review_task_timeout等运行参数。深入配置以下修改都在刚复制的.github/workflows/ocr-review.yml中进行。背景上下文--background是对结果影响最大的单个参数。传入 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务必通过env:传递受 PR 控制的值而不要将${{ }}直接拼进run:——GitHub 会在 shell 解析之前对${{ }}做文本替换PR 标题或分支名中若含 shell 元字符可能造成 runner 上的命令注入。自定义规则通过--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 见 审查规则。从源码结构看cmd/opencodereview/review_cmd.go会在启动时把规则路径交给loadCommonContext加载规则解析器同时.opencodereview/rule.json会被以较高优先级自动读取见action.yml中Resolve review range步骤的注释这解释了为什么修改这两个文件之一都会影响审查输出、进而使检查点失效。并行度默认并行运行 8 个文件组子代理。大型 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对应地cmd/opencodereview/review_cmd.go中agent.NewCommentWorkerPool(opts.concurrency)与MaxConcurrency: opts.concurrency直接由该参数驱动。触发模式默认在 PR打开时以及 PR 内以/open-code-review或open-code-review开头的评论时运行。两种常见定制在更多 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.0复合 action 也提供ocr_version输入默认latest并会在安装后解析版本号——effort需要 v1.10.0、stream_progress需要 v1.9.8旧版本会以明确错误提前终止见action.yml的Install OpenCodeReview步骤。以 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用于获取 diffMetadata: Read-only必需。在应用设置页创建并下载私钥.pem文件同时记下App ID。将应用安装到需要 OCR 审查的仓库。安装后 URL 中的数字即Installation ID例如https://github.com/settings/installations/12345→ ID 为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: | # ...existing post script...此后审查将以应用身份而非github-actions[bot]发布。将发现上传到 GitHub Code ScanningSARIF--format sarif将 SARIF 2.1.0 报告写入 stdout。重定向到文件后用 CodeQL 的upload-sarifaction 上传发现即可出现在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——需要运行完整 review或ocr scan才能生成报告。故障排查症状原因 / 修复Cannot find merge-basecheckout 使用了浅克隆而区间审查需要完整历史。标准工作流为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 中尚未实现因此OCR_DEBUG: 1不会起任何作用文档保留它是为未来实现预留。当前要获取详细输出请查看工作流写入的/tmp/ocr-result.json与/tmp/ocr-stderr.log或在本地运行ocr review。GitLab CI 集成管道做了什么标准管道examples/gitlab_ci/.gitlab-ci.yml具备以下能力MR 事件触发监听merge_requests的全部事件创建、更新、重新打开。Node 20 环境运行于node:20镜像安装 OCR、用ocr config set配置、以 MR diff 模式运行主命令。讨论发布用内置 Python 脚本解析 JSON 对象将每条意见发布为 GitLab Discussiondiff 内嵌通过 MRversions端点计算正确的base_sha/start_sha/head_sha实现精确定位见examples/gitlab_ci/post_review.py的fetch_diff_refs实现。无法内嵌发布的评论回退为普通 MR 备注最后发布汇总备注。产物与统计审查结果写入项目内.ocr/目录GitLab Runner 拒绝构建目录外的路径以 artifacts 保留并通过 dotenv 报告.ocr/ocr-stats.env含OCR_COMMENTS_*与OCR_SUMMARY_URL向后续 job 暴露统计。安装将管道放到仓库根目录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否否模型名。OCR 无内置默认模型必须显式指定。GITLAB_API_TOKEN否是带api作用域的 Project/User/Group Access Token。可选缺失时回退到内置CI_JOB_TOKEN例如 fork 仓库的 MR。可靠性起见推荐独立配置GITLAB_API_TOKEN。GitLab 会拒绝短于 8 字符的变量因此管道中llm.use_anthropic被硬编码为false。使用 Anthropic Claude 模型时请直接修改脚本。与 GitHub 版本一致管道启动时同样会执行ocr config set llm.extra_body {thinking: {type: disabled}}以兼容不支持的提供商需要开启思考模式时删除该行。机器人命名速成技巧Project Access Token 与 Group Access Token 的名称会显示在 MR 讨论旁。将令牌命名为OpenCodeReview Bot无需额外配置即可获得品牌化审查者外观若需要更持久的服务账号配置见下文以服务账号身份发布。深入配置以下修改都在刚复制的.gitlab-ci.yml中进行。背景上下文将 MR 标题传入--background标题遵循feat(auth): add OAuth2 support语义化约定时效果最佳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使用CI_COMMIT_SHA而非源分支名以便同时正确解析同仓库与 fork 仓库的 MR管道头部注释对此有专门说明。自定义规则与并行度复用 GitHub Actions 模板中的同一组参数--rule指定项目规则文件--concurrency限制并行子代理数默认 8每文件组一个script: - | ocr review --rule ./my-rules.json --concurrency 5 \ --from origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME \ --to ${CI_COMMIT_SHA}规则 Schema 见 审查规则。固定 OCR 版本script: - npm install -g alibaba-group/open-code-review1.0.0也可通过OCR_VERSION变量默认latest支持1.8.8或~1.8这类 npm 版本规格实现可复现审查。避免每次推送都重复审查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) # ...otherwise call ocr review ... as usual and write the JSON to # the file the posting step expects.如需强制重新审查删除 MR 中先前的 OCR 备注即可下次运行探测不到 OCR 备注就会继续。本地 GitLab代码无需修改。发布脚本读取CI_SERVER_URLGitLab 在每个 runner 上自动设置因此无需额外配置即可指向你的本地实例。只需确保GITLAB_API_TOKEN由本地实例签发而非gitlab.com。以服务账号身份发布 {#post-under-a-service-account-identity}默认讨论以GITLAB_API_TOKEN持有者身份发布。替换为项目服务账号即可获得OpenCodeReview Bot之类的品牌化名称在Project → Settings → Service Accounts → New service account创建服务账号。所选名称如OpenCodeReview Bot将显示在 MR 讨论旁。在Settings → Members → Invite member邀请它进入项目分配Developer或Maintainer角色两者都拥有发布讨论所需权限。在Settings → Service Accounts →目标账号→ Add new token签发访问令牌所需作用域为api。令牌只显示一次立即复制。在Settings → CI/CD → Variables中替换GITLAB_API_TOKEN的值为该服务账号令牌变量名保持不变。此后讨论将以服务账号身份而非原令牌创建者身份发布。故障排查症状原因 / 修复Cannot find merge-baseRunner 使用了浅克隆。标准管道设置GIT_DEPTH: 0强制完整拉取编辑文件时请保留。发布时API error 403GITLAB_API_TOKEN缺少api作用域、令牌不属于项目成员或本地 GitLab 场景令牌由其他实例签发。请以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 写入.ocr/ocr-result.jsonstderr 写入.ocr/ocr-stderr.log。可在调试阶段输出它们以检查 OCR 响应script: - cat .ocr/ocr-result.json - cat .ocr/ocr-stderr.logJSON 输出格式对接自研 CI 的基础两个模板的核心都是机器可读输出。ocr review --format json --audience agent的 stdout 是一个单一 JSON 文档格式细节见 CLI 参考 · JSON。顶层字段如下字段说明statussuccess、completed_with_warnings、completed_with_errors或skipped。llm解析后的 LLM 身份。model始终存在provider仅在指定了具名 provider 时存在。message可选。人类可读摘要如No comments generated. Looks good to me.。summary可选。运行聚合files_reviewed、comments、total_tokens、input_tokens、output_tokens、cache_read_tokensomitempty、cache_write_tokensomitempty、elapsed。skipped运行中省略。comments始终存在可能为空数组。每条包含path、content、start_line、end_line、existing_code、suggestion_code、thinking等字段。warnings可选。一个或多个子代理失败时出现每条描述受影响的文件与错误。session_id可选。持久化审查运行中出现可传给ocr review --resume session-id重试兼容的区间或提交审查。resume可选。续跑运行时出现含resumed_from、reused_files、rerun_files、previous_model、current_model。没有文件符合审查条件时JSON 模式输出skipped信封让调用方能区分无变更与无发现。从实现看cmd/opencodereview/review_cmd.go通过newQuietHandle(opts.outputFormat, opts.audience)抑制执行期间的进度输出--audience human时[ocr]进度行走 stderrstdout 仍是单文档 JSON因此ocr review --format json | jq .summary这类管道始终可用。要撰写自研 CI 脚本理解此信封结构是第一步。参见CLI 参考——--format、--audience等全部命令行参数与 JSON 输出格式定义两个模板均以其为基础适合从零编写自研 CI 脚本时参考。配置——OCR 支持的全部环境变量与配置键。审查规则——--rule自定义规则文件的 Schema。GitHub Actions 示例 与 复合 Action 定义——前者的可运行完整工作流后者的全部输入/输出参数。GitLab CI 示例、发布脚本 与其 README。除 GitHub 与 GitLab 外仓库的 examples 目录 还提供了 Bitbucket Pipelines、Codeup、Gerrit、GitFlic 等其他 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-review创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考