`shipmates-gh`

Structured GitHub CLI wrapper — the gh patterns shipmates commands use every day.

Shipmates: Structured GitHub CLI wrapper for shipmates workflows — issues, PRs, CI checks, labels, releases, and run logs with validated inputs and JSON results. Reach for this instead of hand-rolling gh shell when fetching issues, opening PRs, polling CI, posting body-file comments, merging with match-head-commit, or searching for duplicate bugs. Requires the GitHub CLI (gh) installed and authenticated. Never a slash command; use it implicitly when the intent calls for one.

What it does

gh wraps the GitHub CLI with a JSON spec: validated repo slugs and issue numbers, body_file hygiene for create/edit/comment/review, and structured JSON results instead of scraped shell output. It covers repo default branch lookup, issue fetch/list/search/create/edit/comment/close, parent/child sub-issue attach/list/detach, PR view/diff/create/checks/poll/comment/review/merge/list, labels, releases, and failed workflow logs — the same operations repeated across /ship-issue, /ship-epic, /pr-review, /consolidate-issues, /plan-epics, and /shipmates-release.

It is a tool, not a command. The crew reach for it when orchestrating GitHub instead of hand-rolling gh bash. Requires the GitHub CLI installed and authenticated (gh auth login); Python side is stdlib-only.

In practice

What it does to a real input:

$ echo '{"op":"repo.view"}' | python3 gh.py
{
  "ok": true,
  "op": "repo.view",
  "result": {
    "nameWithOwner": "owner/repo",
    "defaultBranch": "main",
    "url": "https://github.com/owner/repo"
  }
}

$ echo '{"op":"pr.checks_poll","number":306}' | python3 gh.py

How the crew reach for it

Tools ship with a plain install; refresh one with shipmates install --harness <name> --with-tools gh, or --with-tools none for crew-only. Pass one JSON spec on stdin: echo '{"op":"repo.view"}' | python3 gh.py. List operations with python3 gh.py --list-ops. Multi-line bodies must use body_file — inline body is capped at 200 chars. Sub-issue ops take plain issue numbers ({"op":"issue.sub_issue_add","number":305,"sub_issue_number":306}) and skip the write when the child is already attached (gh's subIssues field is a connection — the op unwraps nodes); they need a host that exposes the parent/child graph, which github.com does and an older Enterprise Server may not.

Reference

Name: shipmates-gh
Description: Shipmates: Structured GitHub CLI wrapper for shipmates workflows — issues, PRs, CI checks, labels, releases, and run logs with validated inputs and JSON results. Reach for this instead of hand-rolling gh shell when fetching issues, opening PRs, polling CI, posting body-file comments, merging with match-head-commit, or searching for duplicate bugs. Requires the GitHub CLI (gh) installed and authenticated. Never a slash command; use it implicitly when the intent calls for one.
Bundled files: gh.py
Install: shipmates install --harness <name> --with-tools shipmates-gh

Where this lives

This page is generated from toolbox/shipmates-gh/tool.md. Opt in at install with --with-tools shipmates-gh and the installer copies the tool — instructions and bundled files — into the harness's skills tree.

View toolbox/shipmates-gh/tool.md on GitHub

Other tools

All tools