gh

gh

gh CLI による GitHub 操作です。PR、issue、リリース、ワークフローの実行、リポジトリ、検索など、一般的な操作をすべて、慣用的でトークン効率のよい呼び出しにまとめています。

ここでの git は読み取り専用です。ログ、差分、ステータスの確認に限られます。コミット、プッシュ、このスキルを使った PR の作成はできません。コミット、プッシュ、PR の作成（単独またはスタック形式）には、関連リポジトリの easy-cheese にある /plate と組み合わせてください。

---

CLI のルール

gh の出力を別の jq バイナリにパイプしないでください。 gh には --jq と --template フラグが用意されています。これらをインラインで指定すれば、jq の起動を避けられ、一部のハーネスで適用される複合コマンドのサンドボックス判定にも引っかかりません。gh ... --jq の出力を xargs や sed などの後続処理にパイプするのは問題ありません。目的は、JSON の抽出を gh 自体の中で行うことです。

# wrong — needs jq binary, triggers a compound command
gh pr list --json number | jq '.[].number'

# right — inline jq, no pipe
gh pr list --json number --jq '.[].number'

# also fine — --jq inlined, then piped to xargs for a bulk op
gh pr list --json number --jq '.[].number' | xargs -I{} gh pr view {}

# Go template alternative
gh pr view 42 --json title --template '{{.title}}'

issue またはコメントの本文にヒアドキュメントの --body を使わないでください。 本文に Markdown の見出しが含まれている場合、$(cat <<'EOF' ... EOF) のパターンは「# hides arguments」のサンドボックス判定に引っかかることがあります。本文をファイルに書き込み、--body-file を渡してください。

gh issue create --title "flaky health-endpoint test" \
  --body-file "$TMPDIR/issue-body.md" --label bug

JSON のフィールド名は必ず --help で確認してください。 GitHub REST API のフィールド名とは異なります。

gh pr list --help | sed -n '/JSON FIELDS/,/^$/p'

よくある注意点：stargazerCount（stargazersCount ではありません）、forkCount（forksCount ではありません）、watchers（watchersCount ではありません）。

---

プルリクエスト

PR の作成は /plate が担当します。このスキルは PR が存在してから使用します。

# Request review on an existing PR
gh pr edit 123 --add-reviewer @copilot

# View
gh pr list                                       # repo PRs
gh pr list --author @me                          # mine
gh pr list --search "is:open label:bug"          # full search syntax
gh pr view 123
gh pr view 123 --web
gh pr diff 123
gh pr diff 123 --exclude '*.lock'                # skip lockfile noise

# Status & checks
gh pr status                                     # PRs touching you
gh pr checks 123                                 # CI checks for the PR
gh pr checks 123 --watch                         # block until done

# Review & merge
gh pr review 123 --approve --body "LGTM"
gh pr review 123 --request-changes --body-file review.md
gh pr merge 123 --squash --delete-branch
gh pr merge 123 --auto --squash                  # auto-merge when checks pass
gh pr update-branch 123                          # bring up to date with base

# Lifecycle
gh pr close 123
gh pr reopen 123
gh pr ready 123                                  # un-draft
gh pr revert 123                                 # creates new revert PR
gh pr checkout 123                               # check out PR branch locally

--jq のフィルターパターンと一括操作については、 references/jq-recipes.md を参照してください。 PR／リリース／CI のエンドツーエンドのスクリプトについては、 references/automation.md を参照してください。

---

Issue

gh issue create --title "..." --body-file body.md --label bug
gh issue create --title "..." --assignee @me

gh issue list                                    # repo issues
gh issue list --label bug --state open
gh issue list --search "is:open label:bug sort:created-desc"

gh issue view 456
gh issue view 456 --web

gh issue edit 456 --add-label needs-triage
gh issue edit 456 --add-assignee @user
gh issue comment 456 --body-file comment.md

gh issue close 456
gh issue close 456 --duplicate-of 123
gh issue reopen 456
gh issue develop 456 --checkout                  # branch off the issue

---

CI／ワークフロー／実行

gh workflow list
gh workflow run ci.yml --ref feature-branch
gh workflow run deploy.yml -f environment=production -f version=v1.2.3

gh run list                                      # all recent runs
gh run list --workflow=ci.yml --status=failure
gh run list --branch=main --limit 10

gh run view 789
gh run view 789 --log                            # full logs
gh run view 789 --log-failed                     # only failed jobs
gh run view 789 --web

gh run watch 789                                 # block until run completes
gh run rerun 789 --failed                        # re-run failed jobs only
gh run cancel 789

# Inspect a run programmatically
gh run view 789 --json status,conclusion,jobs \
  --jq '.jobs[] | select(.conclusion=="failure") | .name'

---

リリース

gh release create v1.0.0                         # interactive
gh release create v1.0.0 --notes-file NOTES.md
gh release create v1.0.0 --generate-notes        # auto-generate from PRs
gh release create v1.0.0 --draft
gh release create v1.0.0 dist/*.tar.gz           # upload assets at create time
gh release upload v1.0.0 dist/*.tar.gz           # add assets later

gh release list
gh release view v1.0.0
gh release download v1.0.0
gh release verify v1.0.0                         # supply-chain attestation

---

リポジトリと検索

gh repo view                                     # current repo
gh repo view owner/repo --json description,stargazerCount,defaultBranchRef
gh repo clone owner/repo
gh repo fork owner/repo --remote
gh repo set-default                              # disambiguate origin

gh search repos "machine learning" --language=python --stars=">1000"
gh search code "TODO" --owner=myorg --language=rust
gh search issues "memory leak" --state=open
gh search prs "refactor" --created=">2024-01-01"

ラベル／codespace／gist／シークレットの操作については、 references/extras.md を参照してください。

---

認証

gh auth login                                    # interactive web login
gh auth login --clipboard                        # auto-copy OAuth code
gh auth status                                   # current identity
gh auth refresh -h github.com -s repo,workflow   # add scopes
gh auth setup-git                                # use gh as git credential helper

よく使われるスコープ：repo（プライベートリポジトリへの書き込み）、workflow（Actions）、admin:org（組織の管理）、write:packages（レジストリ）。

呼び出しが HTTP 401 を返した場合は、gh auth refresh を実行してください。HTTP 403 Resource not accessible by personal access token が返された場合は、スコープが不足しています。gh auth refresh -s <scope> を再実行してください。詳しい診断については、references/troubleshooting.md を参照してください。

---

このスキルでは行わないこと

• ステージング、コミット、プッシュ、PR の作成、リベースなど、作業ツリーを変更する操作。これらは /plate の担当です
• コード品質のレビュー。専用のレビュー用スキルを使用してください
• ワークツリーの作成。対象外です
• 破壊的な操作。 gh repo delete、gh release delete、gh secret delete、gh ssh-key delete、gh codespace delete など、元に戻せないコマンドはこのスキルの対象外です。明示的にユーザーの確認を得た場合に限り実行し、自動化に組み込まないでください。

注意点

• cd <dir> && git ... の複合コマンドは、ハーネスのベアリポジトリ向けサンドボックス判定によってブロックされる場合があります。代わりに git の -C <dir> フラグを使うか、ワークツリーのルートから実行してください。
• **Markdown の見出しを含むヒアドキュメントの --body**は、「# hides arguments」ガードに引っかかります。必ず --body-file を使用してください。
• gh api による直接呼び出しは、名前付きサブコマンドより不安定で、必要になることもほとんどありません。サブコマンドがある場合は、gh api より gh pr ...、gh issue ...、gh run ... を優先してください。gh api は、対応するサブコマンドがないエンドポイントにのみ使用してください。
• レート制限：gh api rate_limit で現在のクォータを確認できます。認証済みのリクエストは 1 時間あたり 5000 件、未認証のリクエストは 1 時間あたり 60 件です。
• デフォルトリポジトリの曖昧さ：クローンに複数のリモートがある場合は、gh repo set-default を一度実行するか、各呼び出しで --repo owner/name を指定してください。

関連項目

• references/jq-recipes.md — PR／実行／イシューのクエリに使える、トークン効率のよい --jq パターン
• references/automation.md — リリースフロー、 CI モニター、一括操作
• references/extras.md — ラベル、Codespaces、 gist、シークレット／変数、プロジェクト、エイリアス
• references/troubleshooting.md — 認証、 権限、レート制限、よくあるエラーコード
• 公式マニュアル：https://cli.github.com/manual