Gerrit API Skill

What this skill does: Query Gerrit changes, read diffs, post code reviews, manage change lifecycle (submit / abandon / restore), and listen to real-time SSH event streams.

Scripts (no pip install needed):

• scripts/gerrit_api.py — REST API operations (cross-platform, Python stdlib)
• scripts/gerrit_stream_events.py — SSH stream-events listener

路径约定: 以下所有 scripts/... 路径均相对于本 Skill 目录（.agents/skills/gerrit-api/）。

✅ Setup Checklist

Complete these steps once before using the skill.

Step 1 — Verify Prerequisites

python3 --version   # must be ≥ 3.9
ssh -V              # must be installed (for stream-events only)

Step 2 — Configure Credentials

Choose one of the two options below. Config file takes priority over env vars.

Option A — Config file (recommended for persistent setups)

Create $WORKSPACE/.config/gerrit-api.json (or ~/.config/gerrit-api.json):

{
  "GERRIT_URL": "https://gerrit.example.com",
  "GERRIT_USERNAME": "john.doe",
  "GERRIT_HTTP_PASSWORD": "your-http-credential-token",
  "GERRIT_DISABLE_SSL_VERIFY": "false",
  "GERRIT_SSH_PORT": "29418",
  "GERRIT_SSH_KEY": "~/.ssh/id_rsa"
}

Option B — Environment variables

# Required
export GERRIT_URL="https://gerrit.example.com"
export GERRIT_USERNAME="john.doe"
export GERRIT_HTTP_PASSWORD="your-http-credential-token"

# Optional — SSL
export GERRIT_DISABLE_SSL_VERIFY="false"  # set to "true" to fix CERTIFICATE_VERIFY_FAILED

# SSH stream-events (optional — defaults derived from GERRIT_URL)
export GERRIT_SSH_HOST="gerrit.example.com"   # default: host from GERRIT_URL
export GERRIT_SSH_PORT=29418                   # default: 29418
export GERRIT_SSH_USERNAME="john.doe"          # default: GERRIT_USERNAME
export GERRIT_SSH_KEY="~/.ssh/id_rsa"          # default: ~/.ssh/id_rsa

Windows CMD / PowerShell:

set GERRIT_URL=https://gerrit.example.com
set GERRIT_USERNAME=john.doe
set GERRIT_HTTP_PASSWORD=your-http-credential-token

⚠️ HTTP Password ≠ Gerrit login password. Generate at: Gerrit → Settings → HTTP Credentials → Generate Password
⚠️ SSH Key must be uploaded: Gerrit → Settings → SSH Keys → Add Key

Step 3 — Verify Environment

python3 scripts/check_env.py [--workspace /path/to/workspace]

Expected: all checks ✅. On error, follow the prompts in the output.

Step 4 — Test the Connection

python3 scripts/gerrit_api.py query "status:open+limit:1"

Expected: JSON output with change data. On SSL error, set GERRIT_DISABLE_SSL_VERIFY=true in config or env.

Step 4 — (Stream Events Only) Test SSH Connection

ssh -p 29418 john.doe@gerrit.example.com gerrit version

Expected: gerrit version 3.x.x

⚡ Quick Reference — Common Commands

All commands: python3 scripts/gerrit_api.py <command> [args]

📖 Full command reference and REST API endpoints: references/rest-api-reference.md

📋 Task Workflows

Workflow A — Review a Change (Step-by-Step Checklist)

Use for performing a code review on a Gerrit change.

Checklist:

• 1. Find changes needing review:

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

• 3. Get the change details for change <id>:

  python3 scripts/gerrit_api.py get-change <id>

• 4. List modified files:

  python3 scripts/gerrit_api.py list-files <id>

• 5. Review each file's diff:

  python3 scripts/gerrit_api.py get-diff <id> "path/to/file.java"

• 6. Post review (choose one option):

  Option A — Inline comments + label in one call:

  python3 scripts/gerrit_api.py review <id> current '{
    "message": "Review comment here.",
    "labels": {"Code-Review": 1},
    "comments": {
      "path/to/file.java": [
        {"line": 42, "message": "Consider a constant here.", "unresolved": true}
      ]
    }
  }'

  Option B — Draft comments first, then publish:

  # Add draft (repeat for each comment)
  python3 scripts/gerrit_api.py create-draft <id> current \
    '{"path":"path/to/file.java","line":42,"message":"Consider a constant.","unresolved":true}'
  # Publish all drafts with a label
  python3 scripts/gerrit_api.py review <id> current \
    '{"message":"See inline comments.","labels":{"Code-Review":-1},"drafts":"PUBLISH"}'

• 7. (Optional) Submit if approved:

  python3 scripts/gerrit_api.py submit <id>

Label values (project-specific, typical):

• Code-Review: -2 reject, -1 needs work, 0 neutral, +1 looks good, +2 approved
• Verified: -1 fails, 0 neutral, +1 verified

Workflow B — Monitor Events with Stream Listener (Step-by-Step Checklist)

Use for reacting to Gerrit events in real time or collecting events for batch processing.

Select the appropriate mode:

Checklist:

• 1. Test SSH: ssh -p 29418 <username>@<host> gerrit version
• 3. Test with dry run (no file writes, verify events arrive):

  python3 scripts/gerrit_stream_events.py \
    --dry-run --summary --max-events 5

• 4. Start the background listener:

  # Write to file + auto-reconnect
  python3 scripts/gerrit_stream_events.py \
    --output events.jsonl \
    --reconnect --quiet &
  echo "Listener PID: $!"

• 5. Filter by event type / project / branch (add as needed):

  --filter patchset-created,change-merged   # only these event types
  --project myOrg/myRepo                    # only this project
  --branch main                             # only this branch

• 6. Read events (from file):

  # Python — reliable cross-platform reader (no jq dependency)
  python3 - <<'EOF'
  import json
  with open("events.jsonl") as f:
      for line in f:
          line = line.rstrip("\n")
          if not line:
              continue
          ev = json.loads(line)
          print(ev["type"], ev.get("change", {}).get("number", ""))
  EOF

• 7. Stop the listener when done: kill <PID>

📖 Full script options, event types, and systemd setup: references/stream-events-guide.md

Configuration Reference

Config Reference

Troubleshooting Checklist

📚 参考文件

⛔ 约束与禁止事项

不支持的场景

明确禁止的操作

• ⛔ 禁止在日志/stderr 中打印 GERRIT_HTTP_PASSWORD、GERRIT_HOOK_TOKEN 或任何凭据字段：不论任何异常情况
• ⛔ 禁止将凭据硬编码在脚本中：必须通过环境变量传入
• ⛔ 禁止对同一 change 的同一 patchset 重复提交 review：非幂等操作，会产生重复评论；调用前检查该 patchset 是否已有本账号评论

边界条件

幂等性声明