GitHub Pull Request
用 GitHub Action 或 ocra review --pr 审查 Pull Request。
GitHub Action
ocra init --github 会写好下文可审查 fork 的 workflow,加 --same-repo-only 时写这一个,并用上你的供应商的 key(ocra init)。手动配置时,在仓库里添加这个 workflow:
name: ocra
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
review:
# A pull request from a fork gets no secrets on pull_request: skip it.
if: github.event.pull_request.head.repo.full_name == github.repository
# One review per pull request at a time: a new push cancels the older run.
concurrency:
group: ocra-${{ github.event.pull_request.number }}
cancel-in-progress: true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- uses: jma49/Open-CR-Agent@6d4d4a21b6334c086e0f884c240d550b2e4c1f46 # v0.7.0
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}- 每个 action 都按提交固定版本,在注释里写明版本号:tag 可以移动,提交不能。本页的方案和
ocra init都这样做,actions/checkout也不例外。git ls-remote --tags https://github.com/jma49/Open-CR-Agent v0.3.0会打印某个版本的提交;Dependabot 会更新固定的提交和注释。 - **保留
fetch-depth: 0:**ocra 需要 base 与 head 之间的历史,浅克隆会停下并给出提示。 - **保留
concurrency:**否则连续两次 push 会把同样的评论发两遍,较慢的那次还可能用更旧的 head 覆盖摘要。被取消的运行不发布任何内容(已在发布时除外),把部分报告留在 job 日志里。 - **把模型 key 存为仓库 secret。**模型来自 base 分支的
.ocra/config.json或env里的OCRA_MODEL_*变量。
遇到 GitHub 限流或短暂故障,ocra 会有限次地重试,但绝不重复可能已经发出评论的请求。
从 v0.1.1 起,Action 从 npm 安装与自身版本相同的 @open-cr-agent/cli,依赖固定在它的 package-lock.json 锁定的版本,不运行安装脚本,使用 npm 官方源时还校验源的签名。只有 ocra 的每个包都带有本仓库发布 workflow 在该版本标签上构建的 provenance 时才使用这些包;否则,或者该版本还没上 npm 时,从自身源码构建并给出警告(v0.1.0 始终如此)。所以 @main 运行的是 main 上的 Action 代码加上 main 所写的发布版;如果此后 main 改了包的依赖,就构建 main。
| 输入 | 默认值 | 含义 |
|---|---|---|
github-token | ${{ github.token }} | 用来读取 PR 和发布评审的 token |
args | 额外的 ocra review 参数,例如 --reviewers correctness,security;按空格和换行拆分(不支持引号) | |
fail-on-concerns | false | 结论为 significant_concerns(存在经核查确认的 critical 问题)时让 job 失败。审查不完整(退出码 3)时 job 总会失败 |
opencode | true | 安装默认运行时 OpenCode。配置里设了 "runtime": "direct" 时可设为 false,见运行时。v0.3.0 新增 |
sarif | false | 同时把审查结果写成 SARIF 2.1.0,用于代码扫描,文件路径见输出 sarif。它会取代 args 里的 --format 和 --output |
给这一步设置 id,就能读取它的输出。只要 ocra 运行过,输出就会设置,步骤失败时也一样;输出来自本次运行写下的会话:随 PR 一起提交的会话,或替代 .ocra/sessions 的链接,都不会被读取。
| 输出 | 含义 |
|---|---|
verdict | approved、approved_with_comments、minor_issues 或 significant_concerns |
exit-code | ocra 的退出码,是 fail-on-concerns 把 1 变成通过之前的值 |
run-id | 运行 id,摘要评论和 SARIF 日志里也有 |
report | JSON 报告的路径,格式同 --format json,位于 $RUNNER_TEMP 下 |
findings | 报告里的问题数 |
sarif | sarif 为 true 时 SARIF 日志的路径 |
只有评审完整完成时(退出码 0 或 1)才会设置 verdict:没审完全部内容的运行(2 或 3)可能写出报告,但其结论不涵盖没审的文件。ocra 没写出报告时,run-id、report 和 findings 为空。保存报告并在 job 摘要里写明结论:
- id: ocra
uses: jma49/Open-CR-Agent@6d4d4a21b6334c086e0f884c240d550b2e4c1f46 # v0.7.0
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
- if: ${{ !cancelled() && steps.ocra.outputs.report != '' }}
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: ocra-report
path: ${{ steps.ocra.outputs.report }}
- if: ${{ !cancelled() }}
env:
VERDICT: ${{ steps.ocra.outputs.verdict }}
FINDINGS: ${{ steps.ocra.outputs.findings }}
RUN_ID: ${{ steps.ocra.outputs.run-id }}
run: echo "ocra: $VERDICT, $FINDINGS findings (run $RUN_ID)" >> "$GITHUB_STEP_SUMMARY"像这里一样通过 env 把输出交给脚本,不要把 ${{ }} 写进 run。
结论只是参考意见(原因):不要用这项检查代替人工审查、把它设为必需的状态检查;打开 fail-on-concerns 时,通过只代表“没有被确认的问题”,不代表“安全”。
在 pull_request 下,来自 fork 的 PR 拿不到 secret,所以 if: 会跳过它们;要审查它们,见来自 fork 的 PR。
运行时
默认运行时 OpenCode 连同原生二进制文件,占 Action 所装 108 个包中的 97 个、175 MB 中的约 165 MB。如果 base 分支配置里的模型都在你声明的端点上,并且配置设了 "runtime": "direct"(选择运行时),设置 opencode: false(v0.3.0 新增),只装 11 个包。此时如果配置选的是 opencode,评审会在调用任何模型之前以退出码 2 停下,并说明缺了哪个包。
- uses: jma49/Open-CR-Agent@<commit> # v0.7.0
with:
opencode: false
env:
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}安装不做缓存:每次运行都用全新的 npm 缓存,所以每个包、签名和 provenance 声明都来自 npm 源,而不会来自其他 workflow 可能写入的缓存。
会发布什么
- 行内评论:落在 diff 内的问题,标明已核实、未核实或未核查,放在同一个
COMMENT评审里。ocra 从不批准 PR。设置github.requestChanges后,结论为significant_concerns时请求修改一次;之后的结论不再阻塞或这个 commit 被放行时撤回(dismiss)。 - 一条摘要评论,在原处更新:结论、总结、diff 之外的问题、已修复的问题、覆盖范围、花费和运行 id。它写明没审到的文件数、是否达到花费上限,并列出只审查了一部分的文件(审查员用完步数或停下)以及该怎么做。
之后的 push 只审查有改动的部分:自上次评审的提交以来改动过的文件,加上上次没审完的文件(任务失败、审查员用完步数、花费上限)。未改动文件里的问题原样沿用:保持打开、计入结论、不重复评论。以下情况会重新审查全部文件:上次的提交已不在分支上(force-push、rebase)、这次 push 让风险档位升高、摘要最后一次由 ocra 以外的人编辑(这时忽略它记录的状态,但 ocra 仍能认出自己没被编辑过的行内评论)、或者传了 --full。只改变运行哪些审查员(reviewers、--reviewers、--ultra)不会;请传一次 --full。摘要会写明本次属于哪种审查以及原因。
与上一次评审对比:
- 已经评论过的问题不会重复评论。
- 只有问题指向的代码已不在文件里或文件已删除,才算已修复;它会被列出,评论串被关闭。
- 这次没被报告、而代码没变的问题列为本次未复现:模型运行有波动,所以它保持打开,按原严重程度计入结论,直到代码被修改或被驳回。同样的代码得到同样的结论。
- 所在文件这次没被审查的问题列为未重新检查,保持打开。
由维护者来做主。维护者,即有写权限(admin、maintain 或 write)且不是 PR 作者的人,resolve 评论串、回复 /ocra dismiss,或者回复以明确的拒绝开头("won't fix"、"will not fix"、"by design"、"false positive"、"not a bug"、"working as intended"、"intended behavior")且不是问句,就驳回了这条问题。被驳回的问题在这个 PR 里不再计入,除非之后的运行以更高严重程度发现它。这些词出现在回复其他位置("this is not intended, good catch"、"is this by design?")不算,"I disagree" 也不算。这些人的其他回复会在问题再次出现时交给 Judge;Judge 可以凭具体理由丢弃它,但已确认的 critical 不行。作者的回复不会交给 Judge,也不能驳回;被别人编辑过的回复不算数。没有行内评论串的问题无法驳回,改用 ocra memory 让它静默:.ocra/memory.json 进入 base 分支后,不论严重程度,每个 PR 都不再报告它。
可提交的建议
一条问题可以带一个修复(fix):替换它所指那几行的代码。这时它的行内评论末尾有一个建议块,有写权限的人可以一键提交(Commit suggestion,或批量提交)。只有评论正好落在被替换的行上时才给出,摘要里从不给;代码要么原样发布,要么不发:含有 HTML 注释开头、/ocra、回车符、控制字符或双向文本字符,或者超过 20,000 个字符时,不附建议块,问题照常发布。建议是模型的提议,提交前请先读一遍。
**计划中:**目前还没有审查员会产生修复,这要等一次经过评估的提示词修改(ADR-0029)。在那之前,评论以文字形式给出建议。
代码扫描
要同时把问题显示为代码扫描(code scanning)告警,用输入 sarif 输出 SARIF,再用 upload-sarif 上传:
permissions:
contents: read
pull-requests: write
security-events: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- id: ocra
uses: jma49/Open-CR-Agent@6d4d4a21b6334c086e0f884c240d550b2e4c1f46 # v0.7.0
with:
sarif: true
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
- uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
# 审查不完整时上一步会失败,这里也照样上传。
if: ${{ !cancelled() && steps.ocra.outputs.sarif != '' }}
with:
sarif_file: ${{ steps.ocra.outputs.sarif }}
category: ocra- 审查仍会发到 PR 上,
report仍指向 JSON 报告:SARIF 只改变 ocra 打印的内容。args: --format sarif --output ocra.sarif效果相同,路径自定。 - 代码扫描只显示带行号的结果,所以文件级问题不显示,之后未改动文件里的早先问题也不显示(之后的 push 只审查改动)。在
args里加--full可以每次都显示全部问题,代价是每次完整审查。 - 公开仓库可以使用代码扫描;私有仓库需要 GitHub Code Security。
- 文件内容见 SARIF 输出。
导入分析工具的结果
先运行 Semgrep、CodeQL 或其他能写 SARIF 的分析工具,再用 --import-sarif 传入日志:落在改动上的结果会和 ocra 自己的问题一起核查和裁决(SARIF 输入)。ocra 自己不运行任何工具。
- run: pipx run semgrep scan --config p/default --metrics=off --sarif --output semgrep.sarif
- uses: jma49/Open-CR-Agent@6d4d4a21b6334c086e0f884c240d550b2e4c1f46 # v0.7.0
with:
args: --import-sarif semgrep.sarif
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}导入用 Semgrep 1.178.0 的日志测试过;这个 workflow 还没在 CI 里端到端跑过。
强制放行阻塞的结论
要合并被 ocra 拦下的改动,由作者以外、有写权限的人评论:
/ocra override <完整的 head commit id> <理由>对这个 commit,退出码从 1 变成 0,fail-on-concerns 通过,requestChanges 的请求撤回。结论仍是 significant_concerns;摘要写明谁、以什么理由放行,并给出带 commit id、可直接复制的命令。新的 push 需要重新放行。要求完整 id,是因为专门构造的 commit 能撞上短前缀。作者不能放行自己的 PR,被他人编辑进评论的命令不算数,审查不完整(退出码 3)绝不会被放行。
PR 能改变什么、不能改变什么
.ocra/config.json、.ocra/rules.json、.ocra/memory.json 和 AGENTS.md 都从 base 提交读取,仓库插件从不加载。diff、标题和描述作为不可信的数据交给审查员。
来自 fork 的 PR
在 pull_request 下,来自 fork 的 PR 拿不到你的 secret,token 也是只读的。pull_request_target 运行默认分支上的 workflow 文件,带着你的 secret 和你授予的权限。下面的 workflow 替换上面那个,你自己分支上的 PR 也由它审查:
name: ocra
on:
pull_request_target:
types: [opened, synchronize, reopened, labeled]
permissions:
contents: read
pull-requests: write
jobs:
review:
# Members and collaborators: every push. Anyone else: one review each
# time a maintainer adds the ocra-review label.
if: >-
(github.event.action == 'labeled' && github.event.label.name == 'ocra-review') ||
(github.event.action != 'labeled' &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association))
# One review per pull request at a time: a new push cancels the older run.
# The key repeats the if:, so a run the if: skips gets a group of its
# own and cannot cancel the review in progress.
concurrency:
group: >-
ocra-${{ github.event.pull_request.number }}-${{
((github.event.action == 'labeled' && github.event.label.name == 'ocra-review') ||
(github.event.action != 'labeled' &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association)))
&& 'review' || github.run_id }}
cancel-in-progress: true
runs-on: ubuntu-latest
steps:
# The base branch. Nothing from the pull request is checked out.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- uses: jma49/Open-CR-Agent@6d4d4a21b6334c086e0f884c240d550b2e4c1f46 # v0.7.0
with:
args: --max-cost-usd 2
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}GitHub 提醒慎用 pull_request_target,是因为构建 PR 代码的 job 会带着你的 secret 运行这些代码。ocra 不运行 PR 里的任何东西(威胁模型);workflow 也要保持这一点:
- **不要在这里检出、安装、构建或测试 PR:**不要写
ref: ${{ github.event.pull_request.head.sha }},不要安装依赖,不要跑测试。这些放到单独的pull_requestworkflow 里,fork 的 PR 在那里拿不到 secret。 - **保留
if:门槛。**任何人都能开 PR,而每次审查都要花钱:外部贡献者的 PR 在维护者每加一次标签时审查一次(下次先移除标签再加上)。外部作者在带标签的审查进行中 push,这次运行会被跳过,那次审查继续进行;要审查新的 head,重新加上标签。--max-cost-usd限制每次审查的花费。 - **把条件留在 concurrency 组名里,改的时候两处一起改。**被
if:跳过的运行(比如加了无关的标签)进入自己的组,不会取消正在进行的审查。 - 使用只用于这些审查的模型 key,并在供应商那里设置花费上限。
- 按提交固定 Action。
只有组织的公开成员,author_association 才是 MEMBER;非公开成员也需要标签。私有仓库请去掉 persist-credentials: false:ocra 会用检出时的凭据获取 PR 的提交。
自己的开发者也改不了的审查
有推送权限的人推送的 workflow 会拿到仓库的 secret,它的 GITHUB_TOKEN 以 ocra 默认信任的 github-actions[bot] 身份发言。要让审查不在他们手里,把三样东西放到只有默认分支才能触及的地方:
- **放 secret 的环境。**创建一个环境,比如
ocra-review(Settings → Environments),在 Deployment branches and tags 里只允许默认分支。把模型密钥移到这里,删掉仓库级的 secret。在默认分支上运行的pull_request_target任务能拿到它;其他分支上推送的 workflow 和on: pull_request都拿不到。 - **ocra 自己的账号。**创建一个 GitHub App,仓库权限给 Pull requests(读写)和 Contents(只读),并安装到仓库上。私钥存为环境 secret
OCRA_APP_KEY,client ID 存为变量OCRA_APP_CLIENT_ID。在默认分支上把github.botLogin设为这个 App 的账号,比如{ "github": { "botLogin": "my-ocra[bot]" } },于是以github-actions[bot]身份发的摘要一律不算数。 - **workflow 和配置需要审查。**保护默认分支,并要求
.github/workflows/和.ocra/的改动经过代码负责人审查(CODEOWNERS)。
name: ocra
on:
pull_request_target:
types: [opened, synchronize, reopened, labeled]
permissions:
contents: read
jobs:
review:
if: >-
(github.event.action == 'labeled' && github.event.label.name == 'ocra-review') ||
(github.event.action != 'labeled' &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association))
# 每个 PR 同一时间只有一次审查:新的 push 会取消较早的运行。
# 组名重复了 if: 的条件,被 if: 跳过的运行进入自己的组,
# 不会取消正在进行的审查。
concurrency:
group: >-
ocra-${{ github.event.pull_request.number }}-${{
((github.event.action == 'labeled' && github.event.label.name == 'ocra-review') ||
(github.event.action != 'labeled' &&
contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association)))
&& 'review' || github.run_id }}
cancel-in-progress: true
runs-on: ubuntu-latest
# 它的 secret 只给在默认分支上运行的任务。
environment: ocra-review
steps:
- id: app
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
with:
client-id: ${{ vars.OCRA_APP_CLIENT_ID }}
private-key: ${{ secrets.OCRA_APP_KEY }}
# 默认分支。不检出 PR 里的任何东西。
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
persist-credentials: false
- uses: jma49/Open-CR-Agent@6d4d4a21b6334c086e0f884c240d550b2e4c1f46 # v0.7.0
with:
github-token: ${{ steps.app.outputs.token }}
args: --max-cost-usd 2
env:
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}上面关于 pull_request_target 的规则照样适用。这套配置还没有完整跑过;如果某一步失败,请提 issue。
配置
{ "github": { "requestChanges": false, "botLogin": "github-actions[bot]" } }botLogin 是哪个账号发的摘要才算 ocra 之前的评审;用别的 token 发布时改成对应账号。即使 ocra 用某个人的 token 发布,它自己的摘要和模型文字里的 /ocra override 等命令也永远不算数。
在命令行里使用
export GITHUB_TOKEN=... # 能读取该仓库的 token
ocra review --pr 42 # 审查并打印,和本地审查一样
ocra review --pr 42 --publish # 同时发布评审token 来自 GITHUB_TOKEN 或 GH_TOKEN;GitHub Enterprise 请设置 GITHUB_API_URL(例如 https://github.example.com/api/v3)并传 --repo。仓库来自 --repo owner/name、GITHUB_REPOSITORY 或指向 github.com 的 origin 远端。缺少的 PR commit 由 ocra 自动拉取。