gerrit-review

Gerrit 代码审查技能

通过 REST API 与 Gerrit Code Review 实例交互。查询开放的变更、读取差异、发布代码审查，并管理变更生命周期（提交、放弃、恢复）。

前置条件

身份验证

辅助脚本按以下顺序检查凭据：

1. ~/.netrc 文件（推荐）——安全性最高；凭据不会出现在进程列表或环境中。
2. 环境变量——当 .netrc 未配置 Gerrit 主机时作为备用方案。

始终需要设置 GERRIT_URL（请在 Shell 配置文件中设置）：

export GERRIT_URL="https://gerrit.example.com"  # no trailing slash

选项 1 — .netrc（首选）

在 ~/.netrc 中为 Gerrit 主机添加条目：

machine gerrit.example.com
login your.username
password your-http-token

保护该文件：chmod 600 ~/.netrc

脚本使用 curl --netrc，因此凭据不会出现在进程列表或 Shell 环境中。

选项 2 — 环境变量（备用方案）

如果在 .netrc 中找不到 Gerrit 主机，脚本会回退到以下变量：

变量	说明
GERRIT_USERNAME	HTTP 用户名（Gerrit → Settings → Profile）
GERRIT_HTTP_PASSWORD	HTTP 凭据令牌（Gerrit → Settings → HTTP Credentials → Generate Password）

重要

HTTP 密码不是用户的登录密码，而是在 Gerrit 网页界面的 Settings → HTTP Credentials → Generate Password 下生成的独立令牌。

如果既未配置 .netrc，也未配置环境变量，脚本会报错退出并提供操作说明。

指导用户时： 始终优先建议使用 .netrc。只有用户无法使用 .netrc 时，才建议使用环境变量。

工具

• curl、jq、base64 — 必需
• python3 — 可选，URL 编码时优先使用；不可用时会回退到 sed

快速开始

使用辅助脚本 scripts/gerrit_api.sh（相对于此 SKILL.md 的路径）：

chmod +x scripts/gerrit_api.sh

./scripts/gerrit_api.sh query "status:open+limit:5"
./scripts/gerrit_api.sh get-change 12345
./scripts/gerrit_api.sh list-files 12345
./scripts/gerrit_api.sh get-diff 12345 "src/main/App.java"
./scripts/gerrit_api.sh get-content 12345 "src/main/App.java"
./scripts/gerrit_api.sh list-comments 12345
./scripts/gerrit_api.sh create-draft 12345 current '{"path":"src/main/App.java","line":23,"message":"Consider renaming this.","unresolved":true}'
./scripts/gerrit_api.sh review 12345 current '{"message":"Looks good!","labels":{"Code-Review":1}}'
./scripts/gerrit_api.sh submit 12345
./scripts/gerrit_api.sh abandon 12345

Gerrit 概念

• 变更 — 一个可审查的单元（一个提交）。每次更新都会创建一个新的补丁集。
• Change-Id — 提交消息中的 Change-Id: I<hex> 页脚，用于将提交关联到 Gerrit 变更。
• 标签 — Code-Review（−2 到 +2）、Verified（−1 到 +1）。取值范围因项目而异。
• 工作流 — 推送到 refs/for/<branch> → 审查者发表评论并投票 → 修改后重新推送 → 获批后提交。

REST API 参考

身份验证

所有请求都使用 /a/ 前缀。辅助脚本会自动处理身份验证（.netrc 或 --user）。

原始 curl 示例（供参考）：

curl -s --netrc "$GERRIT_URL/a/changes/?q=status:open" | tail -n +2 | jq .

输出格式

响应的第一行以 XSSI 前缀 )]}' 开头。解析前请将其去除（tail -n +2）。辅助脚本会自动处理。

URL 编码

项目名称和文件路径必须进行 URL 编码（/ → %2F）。辅助脚本会自动处理。

关键端点

#	操作	方法	端点	辅助命令
1	查询变更	GET	/a/changes/?q=<query>&n=<limit>&o=<option>	query
2	获取变更详情	GET	/a/changes/<id>?o=CURRENT_REVISION&o=DETAILED_LABELS	get-change
3	列出文件	GET	/a/changes/<id>/revisions/<rev>/files/	list-files
4	获取文件差异	GET	/a/changes/<id>/revisions/<rev>/files/<file>/diff	get-diff
5	获取文件内容	GET	/a/changes/<id>/revisions/<rev>/files/<file>/content	get-content
6	列出已发布评论	GET	/a/changes/<id>/comments	list-comments
7	发布评审	POST	/a/changes/<id>/revisions/<rev>/review	review
8	创建草稿	PUT	/a/changes/<id>/revisions/<rev>/drafts	create-draft
9	提交	POST	/a/changes/<id>/submit	submit
10	放弃	POST	/a/changes/<id>/abandon	abandon
11	恢复	POST	/a/changes/<id>/restore	restore
12	添加评审者	POST	/a/changes/<id>/reviewers	add-reviewer
13	设置主题	PUT	/a/changes/<id>/topic	set-topic

<id> 可以是数字变更编号、project~branch~Change-Id，也可以只是 Change-Id。 <rev> 是修订版/补丁集；使用 current 表示最新版本。

查询运算符

status:open、status:merged、status:abandoned、owner:self、reviewer:self、project:<name>、branch:<name>、is:watched、after:"2025-01-01"、before:"2025-12-31"

常用的 o 参数：CURRENT_REVISION、DETAILED_LABELS、DETAILED_ACCOUNTS、CURRENT_FILES、MESSAGES

ReviewInput JSON（用于 review 命令）

{
  "message": "Overall review comment",
  "labels": {"Code-Review": 1},
  "comments": {
    "src/main/App.java": [
      {"line": 23, "message": "Consider renaming.", "unresolved": true},
      {"range": {"start_line": 50, "start_character": 0, "end_line": 55, "end_character": 20}, "message": "Refactor this block."}
    ]
  },
  "notify": "OWNER",
  "drafts": "PUBLISH"
}

标签值（常见）：Code-Review −2 表示拒绝，−1 表示看起来有问题，0 表示不评分，+1 表示看起来不错，+2 表示批准。Verified −1 表示未通过，+1 表示已验证。

comments 的其他字段：in_reply_to（UUID）、unresolved（布尔值；true 表示需要处理，false 表示仅供参考）、fix_suggestions（建议修复方案数组）。

CommentInput JSON（用于 create-draft 命令）

{"path": "src/main/App.java", "line": 23, "message": "[nit] trailing whitespace", "unresolved": true}

代码评审工作流

步骤 1 — 查找变更

./scripts/gerrit_api.sh query "status:open+reviewer:self+-owner:self"

步骤 2 — 检查

./scripts/gerrit_api.sh get-change 12345
./scripts/gerrit_api.sh list-files 12345
./scripts/gerrit_api.sh get-diff 12345 "path/to/file.java"

步骤 2a — 将以往评审评论用作上下文

评审新的补丁集之前，请检查之前已发布的评论：

./scripts/gerrit_api.sh list-comments 12345

将这些评论用作额外的评审上下文：

• 重点关注之前需要处理的评论（unresolved: true、设计方面的问题、要求添加的测试、命名、API 变更）
• 检查最新补丁集的差异，以及相关评论路径对应的当前文件内容
• 判断每个先前提出的问题是否已完全解决、部分解决或仍未解决
• 避免重复已解决的评论；对于仍存在的问题，适当使用 in_reply_to 引用先前的讨论串

典型的后续处理流程：

./scripts/gerrit_api.sh list-comments 12345
./scripts/gerrit_api.sh list-files 12345 current
./scripts/gerrit_api.sh get-diff 12345 "path/to/file.java" current
./scripts/gerrit_api.sh get-content 12345 "path/to/file.java" current

检查最新补丁集是否解决了先前评论的问题时，请比较：

1. list-comments 中最初提出的问题
2. 同一文件/区域的当前补丁集差异
3. 补丁集之后的当前文件内容

如果最新补丁集解决了问题，请勿再次提出。如果问题仅得到部分解决，请发布有针对性的后续评论，说明仍有哪些问题。

步骤 3 — 发布评审

选项 A — 逐步创建草稿： 逐条创建草稿，然后发布：

./scripts/gerrit_api.sh create-draft 12345 current '{"path":"file.java","line":42,"message":"Use a constant.","unresolved":true}'
./scripts/gerrit_api.sh review 12345 current '{"message":"See comments.","labels":{"Code-Review":-1},"drafts":"PUBLISH"}'

选项 B — 一次性评审： 一次发布所有内容：

./scripts/gerrit_api.sh review 12345 current '{"message":"Looks solid.","labels":{"Code-Review":1},"comments":{"file.java":[{"line":42,"message":"Use a constant.","unresolved":true}]}}'

步骤 4 — 提交

./scripts/gerrit_api.sh submit 12345

故障排查

问题	解决方案
401 Unauthorized	检查 .netrc 条目或 GERRIT_USERNAME/GERRIT_HTTP_PASSWORD。在 Gerrit 设置中重新生成 HTTP 密码。
404 Not Found	确认变更编号。检查 GERRIT_URL 末尾是否有斜杠。确保包含 /a/ 前缀。
409 Conflict	可能正在审核变更编辑，或尚未满足提交要求。
JSON 解析错误	确保已移除 XSSI 前缀 )]}'\n（辅助脚本会处理）。
URL 编码问题	路径中的 / 需要编码为 %2F。辅助脚本会处理。
无凭据错误	将 Gerrit 主机添加到 ~/.netrc（首选），或设置环境变量。

注意事项

• GERRIT_URL 可以出现在输出中，但绝不要在日志或输出中打印 GERRIT_HTTP_PASSWORD 或凭据。
• 确保 ~/.netrc 的权限为 chmod 600。
• 此技能用于交互式使用，可能无法涵盖 Gerrit API 的所有边缘情况。

参考资料

• Gerrit REST API 文档
• Gerrit Changes REST API
• Gerrit 搜索运算符
• 5 分钟了解 Gerrit