# Gerrit 代码审查技巧此技能使您能够通过其 REST API 与 Gerrit Code Review 实例进行交互。使用它来查询未完成的更改、读取差异、发布代码审查以及管理更改生命周期（提交、放弃、恢复）。 ## 先决条件 ### 环境变量您**必须**设置以下环境变量：变量|描述 |示例 ---|---|--- `GERRIT_URL` | Gerrit 实例的基本 URL（无尾部斜杠）| `https://gerrit.example.com` `GERRIT_USERNAME` |来自 Gerrit → 设置 → 配置文件 | 的 HTTP 用户名`约翰·多伊` `GERRIT_HTTP_PASSWORD` |来自 Gerrit 的 HTTP 凭证令牌 → 设置 → HTTP 凭证 → 生成密码 | `a1b2c3d4e5...` > [!重要] **HTTP 密码** 不是用户的登录密码。它是在 Gerrit Web UI 的 **设置 → HTTP 凭证 → 生成密码** 下生成的单独令牌。 ### 工具 * `curl` — 用于所有 REST API 调用 * `jq` — 用于 JSON 解析和漂亮打印 * `base64` — 用于解码文件内容响应 ## 快速入门使用“scripts/gerrit_api.sh”（相对于此 SKILL.md 定位）中的帮助程序脚本进行常见操作： # 使脚本可执行（一次性） chmod +x 脚本/gerrit_api.sh # 查询打开的变更 ./scripts/gerrit_api.sh 查询“status:open+limit:5” # 获取变更详情 ./scripts/gerrit_api.sh 获取更改 12345 # 列出修订版中更改的文件 ./scripts/gerrit_api.sh 列表文件 12345 # 获取文件差异 ./scripts/gerrit_api.sh get-diff 12345“src/main/App.java” # 获取原始文件内容 ./scripts/gerrit_api.sh get-content 12345“src/main/App.java” # 发布带有 Code-Review +1 标签的评论 ./scripts/gerrit_api.sh 审查 12345 当前 '{"message":"看起来不错！","labels":{"Code-Review":1}}' # 提交更改 ./scripts/gerrit_api.sh 提交 12345 # 放弃更改 ./scripts/gerrit_api.sh 放弃 12345 ## Gerrit 概念 ### 变更和补丁集 * **更改** 是一个可审查的单元（对应于一次提交）。 * 对更改的每次更新都会创建一个新的**补丁集**（具有相同“Change-Id”的新提交）。 * 更改位于 Git 存储库中的 `refs/changes/` refs 下。 ### 更改 ID * 提交消息中的页脚行 (`Change-Id: I`) 将提交链接到 Gerrit 更改。 * `commit-msg` 钩子（从 Gerrit 安装）自动生成这个。 ### 标签 * **代码审查**：通常为−2 至+2。 “+2”表示已批准。 * **已验证**：通常为−1 至+1。通常由 CI 设置。 * 标签范围和名称是特定于项目的。 ### 工作流程 1. 推送到 `refs/for/` 以创建/更新更改以供审核。 2. 审稿人通过标签添加评论并投票。 3. 修改提交（`git commit --amend`）并重新推送新的补丁集。 4. 一旦获得批准，提交者就会提交更改。 ## REST API 参考 ### 身份验证所有经过身份验证的请求都使用“/a/”前缀和 HTTP 基本身份验证： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ “$GERRIT_URL/a/changes/?q=状态：开放+限制：5” ### 输出格式 Gerrit JSON 响应在第一行以 **XSSI 预防前缀** `)]}'` 开头。您必须在解析之前将其剥离： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ “$GERRIT_URL/a/changes/?q=status:open”|尾-n +2 | jq . ### URL 编码 URL 中的项目名称、文件路径和分支名称必须进行 URL 编码。项目/文件路径中的正斜杠变为“%2F”： myOrg/myProject → myOrg%2FmyProject src/main/App.java → src%2Fmain%2FApp.java ### 关键端点 #### 1\.查询变更 GET /a/changes/?q=<查询>&n=<限制>&o=<选项> 常用查询运算符： * `状态：打开` / `状态：合并` / `状态：放弃` * `所有者：自我` / `评论者：自我` * `项目：<名称>` / `分支：<名称>` * `是：已观看` / `是：已加星标` * `之后："2025-01-01"` / `之前："2025-12-31"` 用于包含额外数据的常见“o”（选项）参数： * `CURRENT_REVISION` — 包括当前修订信息 * `DETAILED_LABELS` — 包括详细的标签/投票信息 * `DETAILED_ACCOUNTS` — 包括完整的帐户信息 * `CURRENT_FILES` — 包含当前修订版的文件列表 * `MESSAGES` — 包括更改消息示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ "$GERRIT_URL/a/changes/?q=status:open+owner:self&n=10&o=CURRENT_REVISION&o=DETAILED_LABELS" \ |尾-n +2 | jq . #### 2\.获取变更详情 GET /a/changes/?o=CURRENT_REVISION&o=DETAILED_LABELS `` 可以是： * 数字更改号码：`12345` * 完整的三元组：`project~branch~Change-Id` * 只是更改 ID：`I8473b95934b5732ac55d26311a706c9c2bde9940` 示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ “$GERRIT_URL/a/changes/12345?o=CURRENT_REVISION&o=DETAILED_LABELS&o=DETAILED_ACCOUNTS”\ |尾-n +2 | jq . #### 3\.列出修订版中的文件 GET /a/changes/<更改 ID>/修订/<修订 ID>/文件/ 使用“current”作为最新补丁集的“”。示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ “$GERRIT_URL/a/changes/12345/revisions/current/files/”\ |尾-n +2 | jq . 响应是“FileInfo”对象的文件路径映射： { "/COMMIT_MSG": { "status": "A", "lines_inserted": 7, "size_delta": 551, "size": 551 }, “src/main/App.java”：{“lines_inserted”：5，“lines_deleted”：3，“size_delta”：98，“size”：23348} } #### 4\.获取文件差异 GET /a/changes/<更改 ID>/revisions/<修订 ID>/files/<文件 ID>/diff `` 必须是 URL 编码的。添加“?intraline”以获取行内差异。示例： FILE_PATH="src%2Fmain%2FApp.java" curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ “$GERRIT_URL/a/changes/12345/revisions/current/files/$FILE_PATH/diff”\ |尾-n +2 | jq . 响应是一个“DiffInfo”实体，其中“content”数组包含“ab”（通用）、“a”（已删除）和“b”（添加）行数组。 #### 5\.获取文件内容 GET /a/changes/<更改 ID>/revisions/<修订 ID>/files/<文件 ID>/内容返回 **base64 编码** 文件内容。示例： FILE_PATH="src%2Fmain%2FApp.java" curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ “$GERRIT_URL/a/changes/12345/revisions/current/files/$FILE_PATH/content”\ | Base64-d #### 6\。发表评论（设置标签、评论） POST /a/changes//revisions//review 内容类型：application/json **ReviewInput** JSON 正文： { "message": "总体评论评论显示在顶部", “标签”：{ “代码审查”：1 }, “评论”：{ “src/main/App.java”：[ { “行”：23， "message": "为了清楚起见，请考虑重命名此变量。" }, { “范围”：{ “起始行”：50， “起始字符”：0， “结束行”：55， “结束字符”：20 }, "message": "这个块应该被重构。" } ] } } 标签值（特定于项目，典型）： * **代码审查** ：`-2`（拒绝），`-1`（看起来错误），`0`（没有得分），`+1`（看起来不错），`+2`（批准） * **已验证** ：“-1”（失败）、“0”（无分数）、“+1”（已验证）示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ -X 发布\ -H“内容类型：application/json”\ -d '{"message":"对我来说看起来不错！","labels":{"Code-Review":1}}' \ “$GERRIT_URL/a/changes/12345/revisions/current/review”\ |尾-n +2 | jq . #### 7\.提交变更 POST /a/changes/<更改 ID>/提交示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ -X 发布\ -H“内容类型：application/json”\ -d '{}' \ “$GERRIT_URL/a/changes/12345/提交”\ |尾-n +2 | jq . #### 8\.放弃/恢复更改 POST /a/changes//abandon POST /a/changes//restore 两者都接受带有“message”字段的可选 JSON 主体： # 放弃 curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ -X 发布\ -H“内容类型：application/json”\ -d '{"message":"被更改 12346 取代"}' \ “$GERRIT_URL/a/changes/12345/放弃”\ |尾-n +2 | jq . # 恢复 curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ -X 发布\ -H“内容类型：application/json”\ -d '{"message":"重新开放以供进一步审查"}' \ “$GERRIT_URL/a/changes/12345/restore”\ |尾-n +2 | jq . #### 9\.添加审稿人 POST /a/changes//reviewers 内容类型：application/json { “审稿人”：“jane.roe@example.com” } 要添加为 CC 而不是审阅者，请添加 `"state": "CC"`。示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ -X 发布\ -H“内容类型：application/json”\ -d '{"reviewer":"jane.roe@example.com"}' \ “$GERRIT_URL/a/changes/12345/reviewers”\ |尾-n +2 | jq . #### 10\.设置主题 PUT /a/changes//topic 内容类型：application/json { “主题”：“我的功能分支” } 示例： curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \ -X 放置 \ -H“内容类型：application/json”\ -d '{"topic":"my-feature-branch"}' \ “$GERRIT_URL/a/changes/12345/topic”\ |尾-n +2 | jq . ## 代码审查工作流程以下是使用此技能执行代码审查的推荐工作流程： ### 第 1 步 — 查找要审核的更改 ./scripts/gerrit_api.sh 查询“status:open+reviewer:self+-owner:self” ### 第 2 步 — 检查更改 # 获取带有标签和当前修订版本的更改详细信息 ./scripts/gerrit_api.sh 获取更改 12345 # 列出修改过的文件 ./scripts/gerrit_api.sh 列表文件 12345 # 读取每个相关文件的差异 ./scripts/gerrit_api.sh get-diff 12345“path/to/file.java” ### 第 3 步 — 发表您的评论 ./scripts/gerrit_api.sh 审查 12345 当前 '{ "message": "总的来说，该方法看起来很可靠。下面有一些建议。", “标签”：{“代码审查”：1}， “评论”：{ “路径/到/file.java”：[ {"line": 42, "message": "考虑在此处使用常量而不是幻数。"} ] } }' JSON 正文中的“comments”字段遵循“CommentInput”实体架构。其他支持的字段包括： * `notify`（字符串）- 电子邮件通知的通知级别（`ALL`、`OWNER`、`NONE` 等，建议使用 `OWNER` 以避免向所有人发送垃圾邮件） * `notify_details`（对象）——每个帐户的细粒度通知控制 * `in_reply_to` (字符串) — 可选，该评论所回复的评论的 URL 编码 UUID。 * `unresolved` (boolean) — 可选，评论线程是否应标记为未解决。建议将代表关键、错误或安全问题的新评论设置为“true”，以便它们保持开放状态，并且必须在合并之前得到解决。对于纯粹的信息性评论或问题已得到解决时，请使用“false”。当问题解决后，审阅者或作者可以稍后解决该线程。 * `fix_suggestions` (数组) — 可选，针对此评论的建议修复列表。每个建议都包含说明和替换补丁。 ### 第 4 步 — 准备好后提交 ./scripts/gerrit_api.sh 提交 12345 ## 故障排除问题 |解决方案 ---|--- `401 未经授权` |检查“GERRIT_USERNAME”和“GERRIT_HTTP_PASSWORD”。在 Gerrit 设置中重新生成 HTTP 密码。 `404 未找到` |验证更改编号是否存在。检查“GERRIT_URL”是否没有尾部斜杠。确保存在“/a/”前缀。 `409 冲突` |您可能正在尝试审核更改编辑，或提交不符合要求的更改。 JSON 解析错误 |确保在解析之前从响应中去除 XSSI 前缀 `)]}'\n`。 URL 编码问题 |带有“/”的项目路径必须使用“%2F”。使用自动处理此问题的帮助程序脚本。 ## 意识 * 此技能专为交互式使用而设计，可能无法处理 Gerrit API 的所有边缘情况。对于复杂的操作，请参考官方API文档。 * `GERRIT_URL` 和 `GERRIT_USERNAME` 可以在技能打印的输出中使用，但**不要**在日志或输出中打印 `GERRIT_HTTP_PASSWORD` 或任何敏感信息。 * 确保 HTTP 凭据令牌 (`GERRIT_HTTP_PASSWORD`) 保持安全，并且不会在日志、环境转储或错误消息中暴露。它只能用于 API 调用中的身份验证，切勿以明文形式打印或记录。 ## 参考文献 * [Gerrit REST API 文档]() * [Gerrit 更改 REST API]() * [Gerrit 搜索运算符]() * [5 分钟了解 Gerrit]()

格里特评论

包含技能