gerrit-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gerrit Code Review Skill

Gerrit Code Review 技能

This skill enables you to interact with a Gerrit Code Review instance through its REST API. Use it to query open changes, read diffs, post code reviews, and manage change lifecycle (submit, abandon, restore).

本技能允许你通过REST API与Gerrit Code Review实例进行交互。你可以用它查询未合并的变更、查看差异、提交代码评审，以及管理变更生命周期（提交、废弃、恢复）。

Prerequisites

前提条件

Environment Variables

环境变量

You must have the following environment variables set:

Variable	Description	Example
`GERRIT_URL`	Base URL of the Gerrit instance (no trailing slash)	`https://gerrit.example.com`
`GERRIT_USERNAME`	HTTP username from Gerrit → Settings → Profile	`john.doe`
`GERRIT_HTTP_PASSWORD`	HTTP credential token from Gerrit → Settings → HTTP Credentials → Generate Password	`a1b2c3d4e5...`

[!IMPORTANT] The HTTP password is NOT the user's login password. It is a separate token generated in the Gerrit web UI under Settings → HTTP Credentials → Generate Password.

你必须设置以下环境变量：

变量	说明	示例
`GERRIT_URL`	Gerrit实例的基础URL（末尾不要加斜杠）	`https://gerrit.example.com`
`GERRIT_USERNAME`	Gerrit → 设置 → 个人资料中的HTTP用户名	`john.doe`
`GERRIT_HTTP_PASSWORD`	Gerrit → 设置 → HTTP凭证 → 生成密码中的HTTP凭证令牌	`a1b2c3d4e5...`

[!IMPORTANT] HTTP密码并非用户的登录密码，它是在Gerrit网页UI的设置 → HTTP凭证 → 生成密码中单独生成的令牌。

Tools

工具

```
curl
```
— used for all REST API calls
```
jq
```
— used for JSON parsing and pretty-printing
```
base64
```
— used for decoding file content responses

```
curl
```
— 用于所有REST API调用
```
jq
```
— 用于JSON解析和格式化输出
```
base64
```
— 用于解码文件内容响应

Quick Start

快速开始

Use the helper script at

scripts/gerrit_api.sh

(located relative to this SKILL.md) for common operations:

bash

undefined

使用位于本SKILL.md同级目录下的辅助脚本

scripts/gerrit_api.sh

执行常见操作：

bash

undefined

Make the script executable (one-time)

为脚本添加执行权限（仅需执行一次）

chmod +x scripts/gerrit_api.sh

Query open changes

查询未合并的变更

./scripts/gerrit_api.sh query "status:open+limit:5"

Get change details

获取变更详情

./scripts/gerrit_api.sh get-change 12345

List files changed in a revision

列出修订版本中变更的文件

./scripts/gerrit_api.sh list-files 12345

Get a file diff

获取文件差异

./scripts/gerrit_api.sh get-diff 12345 "src/main/App.java"

Get raw file content

获取原始文件内容

./scripts/gerrit_api.sh get-content 12345 "src/main/App.java"

Post a draft comment on a specific line

在指定行发布草稿评论

./scripts/gerrit_api.sh create-draft 12345 current '{"path":"src/main/App.java","line":23,"message":"Consider renaming this.","unresolved":true}'

Post a review with a Code-Review +1 label

发布带Code-Review +1标签的评审

./scripts/gerrit_api.sh review 12345 current '{"message":"Looks good!","labels":{"Code-Review":1}}'

Submit a change

提交变更

./scripts/gerrit_api.sh submit 12345

Abandon a change

废弃变更

./scripts/gerrit_api.sh abandon 12345

undefined

./scripts/gerrit_api.sh abandon 12345

undefined

Gerrit Concepts

Gerrit 核心概念

Changes and Patch Sets

变更与补丁集

A change is a single reviewable unit (corresponds to one commit).
Each update to a change creates a new patch set (a new commit with the same
```
Change-Id
```
).
Changes live under
```
refs/changes/
```
refs in the Git repo.

变更是一个可评审的独立单元（对应一次提交）。
对变更的每次更新都会创建一个新的补丁集（具有相同
```
Change-Id
```
的新提交）。
变更存储在Git仓库的
```
refs/changes/
```
引用下。

Change-Id

A footer line in the commit message (
```
Change-Id: I<hex>
```
) that links commits to Gerrit changes.
The
```
commit-msg
```
hook (installed from Gerrit) auto-generates this.

提交消息中的页脚行（格式为
```
Change-Id: I<十六进制字符串>
```
），用于将提交与Gerrit变更关联。
从Gerrit安装的
```
commit-msg
```
钩子会自动生成该标识。

Labels

评审标签

Code-Review: Typically −2 to +2.
```
+2
```
means approved.
Verified: Typically −1 to +1. Usually set by CI.
Label ranges and names are project-specific.

Code-Review：通常范围是−2到+2，
```
+2
```
表示批准。
Verified：通常范围是−1到+1，一般由CI系统设置。
标签的范围和名称是项目特定的。

Workflow

工作流程

Push to
```
refs/for/<branch>
```
to create/update a change for review.
Reviewers add comments and vote via labels.
Amend the commit (
```
git commit --amend
```
) and re-push for new patch sets.
Once approvals are met, a committer submits the change.

推送到
```
refs/for/<分支名>
```
以创建/更新待评审的变更。
评审者添加评论并通过标签投票。
修改提交（
```
git commit --amend
```
）并重新推送以生成新的补丁集。
满足所有批准条件后，由提交者合并变更。

REST API Reference

REST API 参考

Authentication

身份验证

All authenticated requests use the

/a/

prefix and HTTP Basic Auth:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  "$GERRIT_URL/a/changes/?q=status:open+limit:5"

所有需要身份验证的请求都使用

/a/

前缀和HTTP基本认证：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  "$GERRIT_URL/a/changes/?q=status:open+limit:5"

Output Format

输出格式

Gerrit JSON responses start with an XSSI prevention prefix

)]}'

on the first line. You must strip it before parsing:

bash

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

Gerrit的JSON响应第一行包含XSSI防护前缀

)]}'

，解析前必须先移除：

bash

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

URL Encoding

URL编码

Project names, file paths, and branch names in URLs must be URL-encoded. Forward slashes in project/file paths become

%2F

myOrg/myProject  →  myOrg%2FmyProject
src/main/App.java  →  src%2Fmain%2FApp.java

URL中的项目名称、文件路径和分支名必须进行URL编码。项目/文件路径中的斜杠需替换为

%2F

：

myOrg/myProject  →  myOrg%2FmyProject
src/main/App.java  →  src%2Fmain%2FApp.java

Key Endpoints

核心接口

1. Query Changes

1. 查询变更

GET /a/changes/?q=<query>&n=<limit>&o=<option>

Common query operators:

status:open

status:merged

status:abandoned

```
owner:self
```
/
```
reviewer:self
```
```
project:<name>
```
/
```
branch:<name>
```
```
is:watched
```
/
```
is:starred
```
```
after:"2025-01-01"
```
/
```
before:"2025-12-31"
```

Common

(option) parameters to include extra data:

```
CURRENT_REVISION
```
— include current revision info
```
DETAILED_LABELS
```
— include detailed label/vote info
```
DETAILED_ACCOUNTS
```
— include full account info
```
CURRENT_FILES
```
— include file list for current revision
```
MESSAGES
```
— include change messages

Example:

bash

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" \
  | tail -n +2 | jq .

GET /a/changes/?q=<查询条件>&n=<数量限制>&o=<扩展选项>

常用查询操作符：

status:open

status:merged

status:abandoned

```
owner:self
```
/
```
reviewer:self
```
```
project:<项目名>
```
/
```
branch:<分支名>
```
```
is:watched
```
/
```
is:starred
```
```
after:"2025-01-01"
```
/
```
before:"2025-12-31"
```

常用

（扩展选项）参数用于包含额外数据：

```
CURRENT_REVISION
```
— 包含当前修订版本信息
```
DETAILED_LABELS
```
— 包含详细的标签/投票信息
```
DETAILED_ACCOUNTS
```
— 包含完整的账户信息
```
CURRENT_FILES
```
— 包含当前修订版本的文件列表
```
MESSAGES
```
— 包含变更相关的消息

示例：

bash

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" \
  | tail -n +2 | jq .

2. Get Change Details

2. 获取变更详情

GET /a/changes/<change-id>?o=CURRENT_REVISION&o=DETAILED_LABELS

The

<change-id>

can be:

A numeric change number:
```
12345
```
The full triplet:
```
project~branch~Change-Id
```

Just the Change-Id:

I8473b95934b5732ac55d26311a706c9c2bde9940

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  "$GERRIT_URL/a/changes/12345?o=CURRENT_REVISION&o=DETAILED_LABELS&o=DETAILED_ACCOUNTS" \
  | tail -n +2 | jq .

GET /a/changes/<变更ID>?o=CURRENT_REVISION&o=DETAILED_LABELS

<变更ID>

可以是：

数字变更编号：
```
12345
```
完整三元组：
```
project~branch~Change-Id
```

仅Change-Id：

I8473b95934b5732ac55d26311a706c9c2bde9940

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  "$GERRIT_URL/a/changes/12345?o=CURRENT_REVISION&o=DETAILED_LABELS&o=DETAILED_ACCOUNTS" \
  | tail -n +2 | jq .

3. List Files in a Revision

3. 列出修订版本中的文件

GET /a/changes/<change-id>/revisions/<revision-id>/files/

Use

current

<revision-id>

for the latest patch set.

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  "$GERRIT_URL/a/changes/12345/revisions/current/files/" \
  | tail -n +2 | jq .

Response is a map of file paths to

FileInfo

objects:

json

{
  "/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 }
}

GET /a/changes/<变更ID>/revisions/<修订版本ID>/files/

使用

current

作为

<修订版本ID>

表示最新的补丁集。

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  "$GERRIT_URL/a/changes/12345/revisions/current/files/" \
  | tail -n +2 | jq .

响应是文件路径到

FileInfo

对象的映射：

json

{
  "/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 File Diff

4. 获取文件差异

GET /a/changes/<change-id>/revisions/<revision-id>/files/<file-id>/diff

The

<file-id>

must be URL-encoded. Add

?intraline

for intraline differences.

Example:

bash

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" \
  | tail -n +2 | jq .

Response is a

DiffInfo

entity with

content

array containing

ab

(common),

(deleted), and

(added) line arrays.

GET /a/changes/<变更ID>/revisions/<修订版本ID>/files/<文件ID>/diff

<文件ID>

必须进行URL编码。添加

?intraline

参数可查看行内差异。

示例：

bash

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" \
  | tail -n +2 | jq .

响应是包含

content

数组的

DiffInfo

实体，

content

数组包含

ab

（公共部分）、

（删除行）和

（新增行）的行数组。

5. Get File Content

5. 获取文件内容

GET /a/changes/<change-id>/revisions/<revision-id>/files/<file-id>/content

Returns base64-encoded file content.

Example:

bash

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

GET /a/changes/<变更ID>/revisions/<修订版本ID>/files/<文件ID>/content

返回base64编码的文件内容。

示例：

bash

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 Review (Set Labels, Comments)

6. 提交评审（设置标签、评论）

POST /a/changes/<change-id>/revisions/<revision-id>/review
Content-Type: application/json

ReviewInput JSON body:

json

{
  "message": "Overall review comment shown at the top",
  "labels": {
    "Code-Review": 1
  },
  "comments": {
    "src/main/App.java": [
      {
        "line": 23,
        "message": "Consider renaming this variable for clarity."
      },
      {
        "range": {
          "start_line": 50,
          "start_character": 0,
          "end_line": 55,
          "end_character": 20
        },
        "message": "This block should be refactored."
      }
    ]
  }
}

Label values (project-specific, typical):

Code-Review:
```
-2
```
(reject),
```
-1
```
(looks wrong),
```
0
```
(no score),
```
+1
```
(looks good),
```
+2
```
(approved)
Verified:
```
-1
```
(fails),
```
0
```
(no score),
```
+1
```
(verified)

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Looks good to me!","labels":{"Code-Review":1}}' \
  "$GERRIT_URL/a/changes/12345/revisions/current/review" \
  | tail -n +2 | jq .

POST /a/changes/<变更ID>/revisions/<修订版本ID>/review
Content-Type: application/json

ReviewInput JSON请求体：

json

{
  "message": "显示在顶部的整体评审评论",
  "labels": {
    "Code-Review": 1
  },
  "comments": {
    "src/main/App.java": [
      {
        "line": 23,
        "message": "建议重命名该变量以提升可读性。"
      },
      {
        "range": {
          "start_line": 50,
          "start_character": 0,
          "end_line": 55,
          "end_character": 20
        },
        "message": "此代码块应进行重构。"
      }
    ]
  }
}

标签值（项目特定，典型范围）：

Code-Review:
```
-2
```
（拒绝）,
```
-1
```
（存在问题）,
```
0
```
（无评分）,
```
+1
```
（看起来不错）,
```
+2
```
（批准）
Verified:
```
-1
```
（验证失败）,
```
0
```
（无评分）,
```
+1
```
（验证通过）

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Looks good to me!","labels":{"Code-Review":1}}' \
  "$GERRIT_URL/a/changes/12345/revisions/current/review" \
  | tail -n +2 | jq .

7. Post a Draft Comment

7. 提交草稿评论

PUT /a/changes/<change-id>/revisions/<revision-id>/drafts
Content-Type: application/json

CommentInput JSON body:

json

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

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"path":"src/main/App.java","line":23,"message":"[nit] trailing whitespace","unresolved":true}' \
  "$GERRIT_URL/a/changes/12345/revisions/current/drafts" \
  | tail -n +2 | jq .

PUT /a/changes/<变更ID>/revisions/<修订版本ID>/drafts
Content-Type: application/json

CommentInput JSON请求体：

json

{
  "path": "src/main/App.java",
  "line": 23,
  "message": "[优化建议] 存在尾随空格",
  "unresolved": true
}

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"path":"src/main/App.java","line":23,"message":"[nit] trailing whitespace","unresolved":true}' \
  "$GERRIT_URL/a/changes/12345/revisions/current/drafts" \
  | tail -n +2 | jq .

8. Submit a Change

8. 提交变更

POST /a/changes/<change-id>/submit

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$GERRIT_URL/a/changes/12345/submit" \
  | tail -n +2 | jq .

POST /a/changes/<变更ID>/submit

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$GERRIT_URL/a/changes/12345/submit" \
  | tail -n +2 | jq .

9. Abandon / Restore a Change

9. 废弃/恢复变更

POST /a/changes/<change-id>/abandon
POST /a/changes/<change-id>/restore

Both accept an optional JSON body with a

message

field:

bash

undefined

POST /a/changes/<变更ID>/abandon
POST /a/changes/<变更ID>/restore

两个接口都接受包含

message

字段的可选JSON请求体：

bash

undefined

Abandon

废弃变更

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD"
-X POST
-H "Content-Type: application/json"
-d '{"message":"Superseded by change 12346"}'
"$GERRIT_URL/a/changes/12345/abandon"
| tail -n +2 | jq .

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD"
-X POST
-H "Content-Type: application/json"
-d '{"message":"被变更12346替代"}'
"$GERRIT_URL/a/changes/12345/abandon"
| tail -n +2 | jq .

Restore

恢复变更

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD"
-X POST
-H "Content-Type: application/json"
-d '{"message":"Re-opening for further review"}'
"$GERRIT_URL/a/changes/12345/restore"
| tail -n +2 | jq .

undefined

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD"
-X POST
-H "Content-Type: application/json"
-d '{"message":"重新开启以进行进一步评审"}'
"$GERRIT_URL/a/changes/12345/restore"
| tail -n +2 | jq .

undefined

10. Add Reviewer

10. 添加评审者

POST /a/changes/<change-id>/reviewers
Content-Type: application/json

json

{
  "reviewer": "jane.roe@example.com"
}

To add as CC instead of reviewer, add

"state": "CC"

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"reviewer":"jane.roe@example.com"}' \
  "$GERRIT_URL/a/changes/12345/reviewers" \
  | tail -n +2 | jq .

POST /a/changes/<变更ID>/reviewers
Content-Type: application/json

json

{
  "reviewer": "jane.roe@example.com"
}

若要添加为关注者而非评审者，需添加

"state": "CC"

字段。

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"reviewer":"jane.roe@example.com"}' \
  "$GERRIT_URL/a/changes/12345/reviewers" \
  | tail -n +2 | jq .

11. Set Topic

11. 设置变更主题

PUT /a/changes/<change-id>/topic
Content-Type: application/json

json

{
  "topic": "my-feature-branch"
}

Example:

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"topic":"my-feature-branch"}' \
  "$GERRIT_URL/a/changes/12345/topic" \
  | tail -n +2 | jq .

PUT /a/changes/<变更ID>/topic
Content-Type: application/json

json

{
  "topic": "my-feature-branch"
}

示例：

bash

curl -s --user "$GERRIT_USERNAME:$GERRIT_HTTP_PASSWORD" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"topic":"my-feature-branch"}' \
  "$GERRIT_URL/a/changes/12345/topic" \
  | tail -n +2 | jq .

Code Review Workflow

代码评审工作流程

Here is a recommended workflow for performing a code review with this skill:

以下是使用本技能执行代码评审的推荐工作流程：

Step 1 — Find changes to review

步骤1 — 查找待评审的变更

bash

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

bash

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

Step 2 — Inspect a change

步骤2 — 检查变更详情

bash

undefined

bash

undefined

Get change details with labels and current revision

获取包含标签和当前修订版本的变更详情

./scripts/gerrit_api.sh get-change 12345

List modified files

列出修改的文件

./scripts/gerrit_api.sh list-files 12345

Read the diff for each relevant file

查看每个相关文件的差异

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

undefined

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

undefined

Step 3 — Post your review

步骤3 — 提交评审

You can either post all comments at once using the

review

endpoint, or incrementally build your review using draft comments and publish them together.

Option A: Incremental Drafts Create drafts one by one for different files or lines. This is useful when you are doing a complex review.

bash

undefined

你可以使用

review

接口一次性提交所有评论，也可以使用草稿评论逐步构建评审内容，然后一起发布。

选项A：逐步添加草稿 为不同文件或行逐个创建草稿评论，适用于复杂评审场景。

bash

undefined

Add an unresolved draft comment

添加一条未解决的草稿评论

./scripts/gerrit_api.sh create-draft 12345 current '{"path":"path/to/file.java","line":42,"message":"Consider using a constant here instead of a magic number.","unresolved":true}'

./scripts/gerrit_api.sh create-draft 12345 current '{"path":"path/to/file.java","line":42,"message":"建议使用常量替代魔术数字。","unresolved":true}'

Once all drafts are created, publish them and add a vote/summary message

所有草稿创建完成后，发布它们并添加投票/总结信息

./scripts/gerrit_api.sh review 12345 current '{ "message": "I left a few comments on the implementation. Please take a look.", "labels": {"Code-Review": -1}, "drafts": "PUBLISH" }'


**Option B: Single Step Review**
Post the summary and all inline comments in a single payload.

```bash
./scripts/gerrit_api.sh review 12345 current '{
  "message": "Overall the approach looks solid. A few suggestions below.",
  "labels": {"Code-Review": 1},
  "comments": {
    "path/to/file.java": [
      {
        "line": 42, 
        "message": "Consider using a constant here instead of a magic number.",
        "unresolved": true
      },
      {
        "line": 65,
        "message": "Nice cleanup here.",
        "unresolved": false
      }
    ]
  }
}'

The

comments

field in the JSON body follows the

CommentInput

entity schema. Additional supported fields include:

```
notify
```
(string) — notification level for email notifications (
```
ALL
```
,
```
OWNER
```
,
```
NONE
```
, etc, suggest using
```
OWNER
```
to avoid spamming everyone)
```
notify_details
```
(object) — fine-grained notification control per account
```
in_reply_to
```
(string) — optional, the URL encoded UUID of the comment to which this comment is a reply.
```
unresolved
```
(boolean) — optional, whether the comment thread should be marked as unresolved. Crucial for Agent behavior: Set to
```
true
```
for comments that require action and must be addressed before merging. Set to
```
false
```
for informational comments, praise, or purely optional nits. Explicitly declaring this state ensures proper tracking in the review UI.
```
fix_suggestions
```
(array) — optional, list of suggested fixes for this comment. Each suggestion includes a description and a replacement patch.

./scripts/gerrit_api.sh review 12345 current '{ "message": "我对实现细节提出了一些评论，请查看。", "labels": {"Code-Review": -1}, "drafts": "PUBLISH" }'


**选项B：一次性提交评审**
在单个请求体中提交总结和所有行内评论。

```bash
./scripts/gerrit_api.sh review 12345 current '{
  "message": "整体方案看起来可行，以下是一些建议。",
  "labels": {"Code-Review": 1},
  "comments": {
    "path/to/file.java": [
      {
        "line": 42, 
        "message": "建议使用常量替代魔术数字。",
        "unresolved": true
      },
      {
        "line": 65,
        "message": "此处的代码清理做得很好。",
        "unresolved": false
      }
    ]
  }
}'

JSON请求体中的

comments

字段遵循

CommentInput

实体schema，支持的额外字段包括：

```
notify
```
（字符串）— 邮件通知级别（
```
ALL
```
,
```
OWNER
```
,
```
NONE
```
等，建议使用
```
OWNER
```
避免打扰所有人）
```
notify_details
```
（对象）— 针对每个账户的细粒度通知控制
```
in_reply_to
```
（字符串）— 可选，回复目标评论的URL编码UUID
```
unresolved
```
（布尔值）— 可选，评论线程是否标记为未解决。对Agent行为至关重要：对于需要处理且合并前必须解决的评论，设置为
```
true
```
；对于信息性评论、表扬或纯可选建议，设置为
```
false
```
。明确声明此状态可确保评审UI中的跟踪正确。
```
fix_suggestions
```
（数组）— 可选，此评论的建议修复列表，每个建议包含描述和替换补丁。

Step 4 — Submit when ready

步骤4 — 准备就绪后提交变更

bash

./scripts/gerrit_api.sh submit 12345

bash

./scripts/gerrit_api.sh submit 12345

Troubleshooting

故障排查

Problem	Solution
`401 Unauthorized`	Check `GERRIT_USERNAME` and `GERRIT_HTTP_PASSWORD` . Re-generate the HTTP password in Gerrit Settings.
`404 Not Found`	Verify the change number exists. Check `GERRIT_URL` has no trailing slash. Ensure the `/a/` prefix is present.
`409 Conflict`	You may be trying to review a change edit, or submit a change that doesn't meet requirements.
JSON parse error	Make sure you strip the XSSI prefix `)]}'\n` from the response before parsing.
URL encoding issues	Project paths with `/` must use `%2F` . Use the helper script which handles this automatically.

问题	解决方案
`401 Unauthorized`	检查 `GERRIT_USERNAME` 和 `GERRIT_HTTP_PASSWORD` 是否正确。在Gerrit设置中重新生成HTTP密码。
`404 Not Found`	验证变更编号是否存在。检查 `GERRIT_URL` 末尾是否无斜杠。确保请求包含 `/a/` 前缀。
`409 Conflict`	你可能正在尝试评审变更编辑，或提交不符合要求的变更。
JSON解析错误	确保在解析前移除响应中的XSSI前缀 `)]}'\n` 。
URL编码问题	包含 `/` 的项目路径必须使用 `%2F` 。使用辅助脚本可自动处理此问题。

Awareness

注意事项

This skill is designed for interactive use and may not handle all edge cases of the Gerrit API. For complex operations, refer to the official API documentation.
```
GERRIT_URL
```
and
```
GERRIT_USERNAME
```
can be used in the output printed by the skill, but do not print
```
GERRIT_HTTP_PASSWORD
```
or any sensitive information in logs or outputs.
Ensure that the HTTP credential token (
```
GERRIT_HTTP_PASSWORD
```
) is kept secure and not exposed in logs, environment dumps, or error messages. It should only be used for authentication in API calls and never printed or logged in plaintext.

本技能专为交互式使用设计，可能无法处理Gerrit API的所有边缘情况。对于复杂操作，请参考官方API文档。
```
GERRIT_URL
```
和
```
GERRIT_USERNAME
```
可在技能输出中显示，但切勿在日志或输出中打印
```
GERRIT_HTTP_PASSWORD
```
或任何敏感信息。
确保HTTP凭证令牌（
```
GERRIT_HTTP_PASSWORD
```
）的安全性，不要在日志、环境转储或错误信息中泄露。它仅应用于API调用的身份验证，切勿以明文形式打印或记录。