gerrit-review

Gerrit コードレビューのスキル

REST API を通じて Gerrit コードレビューのインスタンスを操作します。オープンな変更を検索し、差分を読み取り、コードレビューを投稿して、変更のライフサイクル（送信、放棄、復元）を管理します。

前提条件

認証

ヘルパースクリプトは、次の順序で認証情報を確認します。

1. ~/.netrc ファイル（推奨） — 最も安全です。認証情報がプロセス一覧や環境変数に表示されません。
2. 環境変数 — Gerrit ホストが .netrc に設定されていない場合のフォールバックです。

GERRIT_URL は常に必要です（シェルのプロファイルに設定してください）。

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

オプション 1 — .netrc（推奨）

Gerrit ホストのエントリーを ~/.netrc に追加します。

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

ファイルを保護します：chmod 600 ~/.netrc

スクリプトは curl --netrc を使用するため、認証情報がプロセス一覧やシェル環境に表示されません。

オプション 2 — 環境変数（フォールバック）

Gerrit ホストが .netrc に見つからない場合、スクリプトは次の環境変数を使用します。

変数	説明
GERRIT_USERNAME	HTTP ユーザー名（Gerrit → Settings → Profile）
GERRIT_HTTP_PASSWORD	HTTP 認証トークン（Gerrit → Settings → HTTP Credentials → Generate Password）

重要

HTTP パスワードはユーザーのログインパスワードではありません。Gerrit のウェブ UI の Settings → HTTP Credentials → Generate Password で生成される、別個のトークンです。

.netrc と環境変数のどちらも設定されていない場合、スクリプトはエラーと手順を表示して終了します。

ユーザーを案内する場合： 必ず最初に .netrc を提案してください。環境変数は、ユーザーが .netrc を使用できない場合にのみ推奨してください。

ツール

• curl、jq、base64 — 必須
• python3 — オプション。URL エンコードに推奨されます。利用できない場合は sed にフォールバックします。

クイックスタート

（この SKILL.md からの相対パスである）scripts/gerrit_api.sh のヘルパースクリプトを使用します。

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 の概念

• 変更 — 1 つのレビュー可能な単位（1 つのコミット）です。更新するたびに新しいパッチセットが作成されます。
• Change-Id — コミットを Gerrit の変更に関連付ける、コミットメッセージ内の Change-Id: I<hex> フッターです。
• ラベル — 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 の Settings で 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