ghish
Skill566 starsChanged 14 days agoApache-2.0View on GitHub
Use the ./gh CLI (gh-ish) for all Gerrit code reviews (CLs, pwrev), LUCI Buildbucket CI checks and tryjobs, Buganizer issues (b/, pwbug.dev), and pushing changes using GitHub CLI syntax.
- Commits and pushes
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- pw_ghish/AGENTS.mdAGENTS.md
- pw_ide/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- BluetoothSkill
- Code ReviewSkill
- crankSkill
- docsSkill
- freshenSkill
- learn-pigweedSkill
- manual-cli-testSkill
- oncallSkill
- pw_async2Skill
- Pigweed Kernel TestingSkill
- C++ Pigweed RPC ServicesSkill
- respondSkill
- reviewSkill
- run-presubmit-checksSkill
- saleae-analyzerSkill
- Use Pigweed Toolchain ToolsSkill
- Multi-Agent Worktree & Bazel Cache ManagementSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 0 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
All commands run via ./gh <family> <subcommand> (or root aliases ./gh view, ./gh diff, ./gh push, ./gh checks, ./gh status, ./gh worktree):
- Very specific: line 108
Update reviewers/assignees: ./gh pr edit --add-reviewer user@google.com (pass --add-owner or --add-reviewer @owners to automatically assign …
- Very specific: line 112
Update the attention set: ./gh pr edit --remove-attention me (--add-attention <email|me>, --remove-attention <email|me>).
- Very specific: line 195
Prefer --auto (auto-submit upon approval) or --trigger (alias --cq.
- Very specific: line 231
Create branch or allocate a warm worktree slot (./gh wt use --issue <id>).
- Very specific: line 233
Create issue (--amend adds Bug: b/<id> or issue.trailer_format to HEAD.
- Very specific: line 242
Use the long form for --auto (-a is --assignee), --publish (-p is --project), --force (-f is --fill), --trigger/--cq (-t is …
- Very specific: line 284
NEVER use raw
git push: Always use ./gh pr push (or ./gh push) to update existing changes with new patchsets, and ./gh pr create to … - Very specific: line 293
Resolve Threads Explicitly: When fixing an issue raised by a reviewer, always reply with --resolved --path <file> [--line <line>].
- Very specific: line 295
Authentication is Automatic: Never use manual curl -sb ~/.gitcookies or gob-curl.
- Very specific: line 313
Submit Changes, Not Patchsets: Use ./gh pr merge <id> --cq (or --auto) without /<patchset> suffixes.
- Very specific: line 315
NEVER Poll CI in an Agent Loop: Run ./gh pr checks --watch --fail-fast as a background command and stop calling tools until notified.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
gh-ish (./gh): Gerrit, Buildbucket & Buganizer CLI
Pigweed provides ./gh (a cached repository wrapper around
//pw_ghish:gh-ish), exposing Gerrit code reviews (./gh pr), LUCI Buildbucket
CI checks (./gh pr checks, ./gh run), Google Issue Tracker / Buganizer
(./gh issue), and worktree pools (./gh wt) through standard GitHub CLI
(gh) syntax.
This skill is the single source of truth for Gerrit, Buildbucket, and Buganizer
workflows in Pigweed, completely replacing legacy raw git push, manual curl
commands, search_builds.py, and .gitcookies scripts.
Quick Command Reference
All commands run via ./gh <family> <subcommand> (or root aliases ./gh view,
./gh diff, ./gh push, ./gh checks, ./gh status, ./gh worktree):
1. Change Targeting & Inspection
Subcommands accepting [<id>] support:
- Omitted argument: Automatically resolves the active change on the current Git branch.
- Change number:
472267or with patchset472267/3. - Gerrit URL:
https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/472267(or/+/472267/3). Automatically routes to the Gerrit host in the URL even when invoked from a different repository. - Shortlink:
pwrev/472267,pwrev.dev/472267,pwrev.dev/i/472267(internal review),fxrev/472267,fxrev.dev/472267,fxr/472267,fxrev.dev/i/472267,fxr/i/472267,ag/472267,aosp/472267,crrev.com/c/472267,crrev.com/i/472267(andgo/<shortlink>orgoto.google.com/<shortlink>forms), plus any custom prefixes configured in.ghish.toml([gerrit.shortlinks]) orgit config ghish.gerrit.shortlink.<prefix>. Automatically resolves the corresponding Gerrit host. - Branch name:
my-feature,cl/472267,change-472267(resolves via branch commitChange-Idorbranch.<name>.gerrit-change-idconfig).
Commands:
./gh pr view [<id>]: View change metadata (patchset, owner, reviewers, attention set, status, labels). Defaults to active change on current branch.-c, --comments: Display all file and inline comment threads (including your unpublished[DRAFT]comments,[PS<N>]patchset numbers, and[resolved]/[unresolved]thread states) indented by file and line number, orComments: Nonewhen empty.--json <fields>: Output structured JSON (e.g.number,title,state,author,files,reviewers,comments,drafts). Unknown fields are strictly rejected.--json bug,bugs: Read back the linked bugs — the Gerrit counterpart to GitHub'sclosingIssuesReferences.bugis a flat"b/123456, b/789"string;bugsis[{"id": "b/123456", "closes": true}], whereclosesdistinguishes aFixed:trailer (closes the bug on submit) from aBug:trailer (links only). Use this to verify a./gh issue create --amendorBug:/Fixed:commit trailer update, and to check whether a bug is already linked before adding one.
./gh pr diff [<id>[/<patchset>]]: View unified patch diff../gh pr checkout [<id>[/<patchset>]]: Fetch and check out change branch or specific patchset locally atFETCH_HEAD.
2. Push & Edit
./gh pr create: Push local commit(s) to Gerrit as a new change.- Safety Guard: Fails with a clear error and URL if the change already
exists (use
pr pushto update existing changes). - Stack Guard: Halts if pushing multiple commits unless
--stackis specified. - Submodule Guard: Enforces
gerrit.submodule_policy("allow","warn-unpushed","require-pushed", or"forbid-manual-rolls", plus automatic detection of Gerrit'sNo-Submodule-Changessubmit requirement) beforegit push. - Multi-Remote & Default Branch: Automatically resolves non-
originremotes (gerrit.remotein.ghish.toml,branch.<cur>.remote,goog,aosp,partner) and default branches (gerrit.default_branch, tracked upstream merge branch,refs/remotes/<remote>/HEAD,main). - Flags:
-t, --title <str>,-b, --body <str>,-F, --body-file <file|->,--bug <id>,--fixed <id>,-r, --reviewer <email|@owners>,--owner,-c, --cc <email>,--auto,--trigger [1|2](alias--cq [1|2]; defaults to+1dry run onCommit-QueueorPresubmit-Ready;2submits),-d, --draft(WIP),-B, --base <branch>,--stack,--publish,-o, --push-option <opt>,--no-verify,--nightly/--submit-at <HH:MM>(see Scheduled submit underpr merge).
- Safety Guard: Fails with a clear error and URL if the change already
exists (use
./gh pr push(aliases:./gh push,./gh pr upload): Push local commit(s) to Gerrit to upload a new patchset on an existing change.- Branch Memory: Automatically queries Gerrit by
Change-Idto discover the CL's target branch (e.g. sandbox branch), guaranteeing updates land on the right branch. - Stack & Submodule Guards: Enforces stack and submodule safety checks before pushing.
- Supports
--ready(remove WIP) and allcreateflags (including-t,-b,-F,--bug,--fixedto safely amendHEAD's commit message and trailers, rolling backHEADautomatically if pre-flight or push fails). - Smart Fallback: If pushed with
--trigger/--cqor metadata on an already up-to-date commit,pr pushautomatically applies updates via the Gerrit API instead of failing.
- Branch Memory: Automatically queries Gerrit by
./gh pr ready [<id>] [--owner] [-r <email|@owners>] [-m <msg>] [-u|--undo]: Mark a change ready for review (or back to WIP with--undo), optionally assigning reviewers or resolving module code owners via--owner/-r @owners../gh pr edit [<id>]: Edit Gerrit CL metadata:- Trigger presubmit / CQ dry run:
./gh pr edit --trigger(alias--cq; or--trigger 2/--cq 2to submit,--trigger 0/--cq 0to remove vote; also supports--add-label <Name>=<Score>). - Update reviewers/assignees:
./gh pr edit --add-reviewer user@google.com(pass--add-owneror--add-reviewer @ownersto automatically assign module code owners; also supports--remove-reviewer,--add-assignee,--remove-assignee). - Update the attention set:
./gh pr edit --remove-attention me(--add-attention <email|me>,--remove-attention <email|me>). Unlike--remove-assignee, this leaves the user as a reviewer. - Set or remove topic/hashtags:
./gh pr edit --topic <name>(--remove-topic,--add-hashtag,--remove-hashtag). Rejects--topicand-o topic=...before pushing if the project setsTopics-Not-Supportedorforbid_topics = truein.ghish.toml. - Commit Messages & Bug Trailers:
pr editonly updates server metadata. To update a CL's commit title, description, orBug:/Fixed:trailers, pass-t/--title,-b/--body,-F/--body-file,--bug, or--fixedon./gh pr push(or./gh pr createfor a new CL).
- Trigger presubmit / CQ dry run:
3. Review & Comment
./gh pr comment [<id>] --path <file> [--line <line>] (-m <msg> | -F <file|->)(or-b <msg>): Stage a file-level or inline comment as a server-side draft (auto-threads onto any existing thread at<file>or<file>:<line>across patchsets) so multiple comments and resolutions can be published together via./gh pr review --publish(or./gh pr push --publish). Pass--body-file -(-F -) with a heredoc (<<'EOF') for multi-line comments containing quotes, backticks, or code blocks.--resolved: Mark thread as resolved (requires--path, and--linefor inline threads).--draft: Save or update comment as an unpublished draft (default with--path; opt-in without--path). Updates an existing draft at that target in place (preservingSideandRange); disambiguate multiple drafts across patchsets with--patchset <N>or<id>/<N>.--publish: Publish an inline/file comment immediately in its own Gerrit review instead of staging a draft. Never use--publishonpr commentwhen replying to or resolving multiple comments; stage all comments first and run./gh pr review --publishonce at the end.--delete-draft: Delete an unpublished draft comment at--path <file> [--line <line>](or omit--pathfor a change-level draft).--agent=false: Pass when posting the user's verbatim words (agent comments are marked AI-generated by default).
./gh pr comment [<id>] (-m <msg> | -F <file|->) [--draft]: Post (or stage with--draft) a change-level comment (-F <file>reads from file;-F -reads fromstdin)../gh pr review [<id>] [--approve | --request-changes] [--trigger [1|2] | --cq [1|2]] [--publish] [-m <msg> | -F <file|->]: Submit review (--approvevotes the change's maximum allowedCode-Reviewscore, e.g.+2or+1;--request-changesvotesCode-Review-1;--publishbatch-publishes all staged drafts across revisions in a single review and email; without--publish, pending drafts stay private). For full review criteria, see.agents/skills/code_review/SKILL.md.
4. Monitor & Rerun CI / Buildbucket & Busytown Checks
./gh pr checks [<id>[/<patchset>]]: Query remote LUCI Buildbucket checks, Android Busytown / TreeHugger presubmit targets (treetop~presubmittasks/ci.android.com), and Gerrit automated submit requirements / verification labels (./pw presubmitruns local host validation).--watch: Monitor checks until all blocking checks finish.--fail-fast: Exit immediately upon the first blocking failure (implies--watch).--log-failed: Automatically display failure reports and log snippets on exit (default:true).-e, --experimental: Include non-blocking experimental checks in output.--all: Include child subbuilds hidden byci.hide_tag_filtersin.ghish.toml.- Exit codes:
0= all blocking checks passed,8= checks still running,1= blocking check failed, canceled, or no checks reported. Branch on the exit code; never scrape the table.0covers CI only, not submittability: also read the trailingNot yet submittable: …line (submitBlockersin--json). - Equivalent Patchsets: Builds from earlier code-equivalent patchsets
(
TRIVIAL_REBASE,TRIVIAL_REBASE_WITH_MESSAGE_UPDATE,NO_CODE_CHANGE,NO_CHANGE,MERGE_FIRST_PARENT_UPDATE) are automatically included and labeled(from patchset <N>). - Gerrit UI Check Count Note:
./gh pr checksreturns top-level Buildbucket builders (e.g. ~72), whereas the Gerrit UI "Checks" tab (~132) also counts individualpw_presubmitsub-steps and static analyzers (AyeAye, SLSA).
./gh run view [<id>] [-j|--job <builder|id>] [--target <target>] [--log-failed] [--log] [--all] [-v] [--json]: Inspect failed builders, LogDog or Busytownbuild.log/ AnTS failure snippets (--log-failed), or the hierarchical step tree (-j [<project>/][<bucket>/]<builder>). For direct Busytown build inspection, passP<bid>/<target>orP<bid> --target <target>../gh run rerun [<id>] [--failed | -j <builder>] [--dry-run]: Rerun all failed builders or a specific builder viabb addon Buildbucket (using each build's recorded<project>/<bucket>/<builder>and skipping child subbuilds tagged withskip-retry-in-gerrit:subbuild) or viatreetop~runaction/Presubmit-Ready+1on Android Busytown / TreeHugger changes../gh run list [<id>] [--all]&./gh run watch [<id>].
5. Listing, Merging & Status
./gh pr list [--limit 30] [--state open|merged|closed|all] [--all-projects] [--json <fields>]: Automatically scopes toproject:<local-repo>when run inside a Git checkout; pass--all-projectsto list across all projects on the Gerrit host../gh pr merge [<id>] [--auto | --trigger | --cq | --nightly | --submit-at <HH:MM>]: Submit change to target branch. Prefer--auto(auto-submit upon approval) or--trigger(alias--cq;Commit-Queue+2orAutosubmit+1+Presubmit-Ready+1) over barepr merge.- Scheduled submit (
--nightly/--submit-at <HH:MM>, also onpr createandpr push): Schedules the submit with a Gerrit Flow. At that time it starts a dry run and enables auto-submit, so the change lands once it is submittable. Running it again replaces the pending schedule. A work-in-progress change is marked ready for review (notifying reviewers).--nightly: a slot in 21:00–03:00 US Pacific (America/Los_Angeles), derived from the change number. Run inside the window after the slot has passed, it schedules the next minute.--submit-at <HH:MM>: 24-hour time in US Pacific, not the user's time zone; convert first. A time already past today means tomorrow.- With
--stack(pr create/pr push), every change is scheduled. The bottom change gets its nightly slot or the--submit-attime, and each change above it 30 minutes later (even past 03:00). - Either flag rejects the other and
--auto.pr create/pr pushalso reject--cq=2and-d, --draft;pr mergealso rejects--cq/--triggerand--message.
- Scheduled submit (
./gh pr status [--all]: Focused dashboard of current branch (including inline[PS<N>]previews for up to 2 unresolved threads and standalone[DRAFT]comments), CLs created by you, and incoming reviews (scoped to last 30 days unless--allis passed)../gh sense [<target>] [--json] [--status] [--fleet](aliases:./gh pr sense,./gh wt sense): Fast parallel context sensor for autonomous workflows (/crank). Inspects local Git state, manual &./gh wtworktrees (including whether<target>bug/CL is already tracked in another slot), active/target Gerrit CL comments & drafts, Buildbucket CI checks, and optional.ghish.tomloncall status in<500ms, classifying the recommended next-step modality.
6. Buganizer Issue Management (./gh issue)
./gh issue status&./gh issue list [--assignee @me|<email>] [--state open|closed|all] [--label P1|S2|bug|vulnerability|component:<id|alias>|hotlist:<id|alias>|!hotlist:<id|alias>] [--search "<q>"]../gh issue view [<id>|<url>] [--comments] [--json <fields>]: View issue (resolvesBug:/Fixed:/Fixes:trailer fromHEADif<id>is omitted)../gh issue develop [<id>] [-b <base>] [-n <name>] [-w|--worktree]: Create branch or allocate a warm worktree slot (./gh wt use --issue <id>)../gh issue create -t <txt> (-b <msg> | -F <file|->) [-C <id>] [--amend]Create issue (--amendaddsBug: b/<id>orissue.trailer_formattoHEAD; pre-commit, pass--bug b/<id>to./gh pr create -t ...); resolves component via-C/-l,.ghish.toml, orOWNERS../gh issue comment [<id>] (-m|-b <msg> | -F <file|->)./gh issue edit [<id>] [-t <txt>] [--add-assignee <email>] [-l <label>]./gh issue close [<id>] [-r <reason>] [--duplicate-of <n>] [-c|-m <msg>]./gh issue reopen [<id>] [-c|-m <msg>]
7. Where gh Habits Break
Use the long form for --auto (-a is --assignee), --publish (-p is
--project), --force (-f is --fill), --trigger/--cq (-t is
--title/--template, -q is --jq), --target on run view (-t is
--template), --all-projects on pr list (-a is --assignee), and
--message on pr merge (-m is --merge).
| You type | Real gh | Here |
pr list -a | assignee | queries Gerrit reviewer: — Gerrit dropped assignees in 3.8. |
pr list -l | issue label | a Gerrit vote predicate, e.g. Code-Review+2. |
run list/view --json | a field list | a boolean; it takes no fields. pr view --json does take fields. |
--json state | OPEN/CLOSED/MERGED | Gerrit's NEW/MERGED/ABANDONED. |
--json status values | strings | always bare ASCII enums ("status": "READY_TO_LAND", "status": "ok"); text-mode glyphs (✓, ●) never appear in them, so compare values directly. |
pr review --request-changes | blocks the PR | votes Code-Review-1, which is advisory. Code-Review-2 is the veto. |
pr comment --draft | (n/a) | an unpublished draft comment nobody else can see — not a WIP change. |
issue -l/--label | free-form text | Buganizer priority/severity/type/hotlist/component (P0–P4, S0–S4, bug, feature, task, vulnerability, hotlist:<id|alias>, component:<id|alias>, prefix -/! to negate in list). |
Key Agent Workflows
Workflow 1: Addressing Review Feedback & Drafts
- Fetch & review comments and drafts:
./gh pr view <id> --comments(or./gh pr status) - Apply fixes & verify locally:
./pw presubmit --mode auto --base origin/main - Upload updated patchset:
git commit -a --amend --no-edit && ./gh pr push - Stage replies & resolve threads (saved as server-side drafts by default when
--pathis specified; pass-F -to read multi-line body fromstdin, or--delete-draftto remove a private steering draft):./gh pr comment <id> --path <file> --line <line> (-m "Fixed." | -F <file|->) --resolved - Batch-publish all staged drafts once:
./gh pr review <id> --publish(or./gh pr push --publish)
Workflow 2: CI Triage & Targeted Retry
- Check or watch status:
./gh pr checks <id>or run./gh pr checks <id> --watch --fail-fastas a background command (never poll in an agent loop!). - Inspect failure logs:
./gh run view <id> --log-failed(or./gh run view <id> -j <builder>). - Rerun failed builders:
./gh run rerun <id> --failed(or-j <builder>). - Full CQ dry run:
./gh pr edit <id> --cq.
Critical Rules for AI Agents
- NEVER use raw
git push: Always use./gh pr push(or./gh push) to update existing changes with new patchsets, and./gh pr createto create new changes. - Stage Inline Comments First, Then Batch-Publish Once:
./gh pr comment --path <file> [--line <line>]stages inline/file comments and thread resolutions as server-side drafts by default. When the user asks to publish comments or resolve threads on Gerrit, stage all replies first and then run./gh pr review [<id>] --publish(or./gh pr push --publish) once at the end so Gerrit emits a single review and notification email. Never pass--publishtopr commentin a loop. - Resolve Threads Explicitly: When fixing an issue raised by a reviewer,
always reply with
--resolved --path <file> [--line <line>]. - Authentication is Automatic: Never use manual
curl -sb ~/.gitcookiesorgob-curl;./ghhandles Gerrit, LUCI, and Buganizer OAuth2/SSO authentication automatically. - Never Ignore Command Failures or Exit Codes: Invalid inputs fail fast with non-zero exit codes. Always inspect stderr and address reported errors.
- Preserve
Change-Idand Commit Trailers: PreserveChange-Idfooters when editing, amending, squashing, or rebasing commits. Prefer./gh pr push --title/--body/-F/--bug/--fixed(or./gh pr create ...) to updateHEAD's commit message and trailers safely. For local rebases or squashes, keep ONLY the earliest commit'sChange-Id, or dump toCOMMIT_EDITMSG_TMP(git log -1 --format=%B HEAD > <tmp>), edit surgically, and apply withgit commit --amend --only -F <tmp>. - Link Bugs With Trailers, Never
Fixes #Nor Fabricated Bug IDs: GitHub'sFixes #456does nothing on Gerrit. UseBug: b/456orFixed: b/456trailers in the commit message (or./gh issue create --amend), and verify with./gh pr view <id> --json bug,bugs. NEVER invent, guess, or placeholder-fill aBug:orFixed:issue number — omit the trailer entirely if no real issue ID was provided or created. - Submit Changes, Not Patchsets: Use
./gh pr merge <id> --cq(or--auto) without/<patchset>suffixes. - NEVER Poll CI in an Agent Loop: Run
./gh pr checks --watch --fail-fastas a background command and stop calling tools until notified.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

