github-cli

GitHub CLI スキル

ターミナルから GitHub のリポジトリ、サービス、API を直接操作するための gh CLI のパターンを紹介します。認証、リポジトリ管理、イシュー、プルリクエスト、アクション、リリース、プロジェクト、検索、REST／GraphQL API を扱います。ブランチ作成、コミット、CI/CD などの Git ワークフローのパターンは、別のスキルで扱います。

クイックリファレンス

領域	主なコマンド
認証	gh auth status、gh auth login、gh auth token
リポジトリ	gh repo clone、gh repo create、gh repo fork、gh repo sync
閲覧	gh browse、gh browse --settings、gh browse file.ts:42
イシュー	gh issue list、gh issue create、gh issue edit、gh issue close
プルリクエスト	gh pr create、gh pr review、gh pr merge、gh pr checkout
アクション	gh run list、gh run view、gh workflow run、gh cache list
リリース	gh release create、gh release list、gh release verify
プロジェクト	gh project list、gh project create、gh project item-add
検索	gh search repos、gh search issues、gh search code
API	gh api repos/{owner}/{repo}、gh api graphql
セキュリティ	gh attestation verify、gh ruleset list、gh secret set
ステータス	gh status、gh pr checks、gh pr status
Codespaces	gh codespace create、gh codespace ssh、gh codespace code

よくあるワークフロー

ワークフロー	コマンド
手早く PR を作成	git push -u origin feat の後に gh pr create --fill
ドラフト PR	gh pr create --draft --fill の後、完了したら gh pr ready
レビューしてマージ	gh pr checkout 45 の後に gh pr review --approve、さらに gh pr merge --squash --delete-branch
PR を自動マージ	gh pr merge --auto --squash（必須のチェックが通るまで待機します）
CI を確認	gh pr checks の後に gh run watch
失敗した CI を再実行	gh run rerun <run-id> --failed
リリースを作成	gh release create v1.0.0 --generate-notes
コードを検索	gh search code "handleAuth" --repo owner/repo
イシューをプロジェクトに追加	gh project item-add 1 --owner @me --url <issue-url>
成果物を検証	gh attestation verify artifact.tar.gz --owner owner
ワークフローを実行	gh workflow run deploy.yml -f environment=production
マージ済み PR を取り消す	gh pr revert 45
フォークを同期	gh repo sync でフォークを上流から更新します

出力形式

gh の多くのリストコマンドと表示コマンドは、スクリプト作成や自動化向けの構造化出力に対応しています。

フラグ	目的
--json	指定したフィールドを JSON として出力
--jq	jq 式で JSON をフィルタリング
-t	Go テンプレートで JSON を整形
--web	リソースをブラウザーで開く
--comments	コメントを含める（issue と PR）

スコープ：リポジトリ、環境、組織

シークレットと変数は、異なるレベルにスコープを設定できます。

スコープ	フラグの例
リポジトリ	gh secret set KEY（デフォルト）
環境	gh secret set KEY --env production
組織	gh secret set KEY --org name --visibility

プロジェクトコマンドでは、常に --owner @me または --owner org-name が必要です。

認証の前提条件

ほとんどのコマンドを実行するには、事前に gh CLI の認証が必要です。gh auth status を実行して、現在のセッションを確認してください。必要なスコープが不足していると、エラーが表示されずに失敗します。再認証せずにスコープを追加するには、gh auth refresh -s scope を使用してください。CI 環境では、対話型ログインの代わりに環境変数 GITHUB_TOKEN または GH_TOKEN を設定してください。

よくある間違い

間違い	正しい方法
ブランチを先にプッシュせずに gh pr create を実行する	PR を作成する前に git push -u origin branch でプッシュする
CI の状態を確認せずに gh pr merge を使用する	先に gh pr checks を実行するか、チェックが完了するまで待つ gh pr merge --auto を使用する
適切に記述されたコミットから PR を作成する際に --fill を忘れる	gh pr create --fill を使用して、コミットからタイトルと本文を自動入力する
ネストされたデータの取得に GraphQL のほうが効率的なのに REST API を使う	1 回の呼び出しで関連オブジェクトを取得するクエリには gh api graphql を使用する
正しいスコープで認証していない	gh auth status でスコープを確認し、gh auth refresh -s scope で追加する
--owner を指定せずに gh project コマンドを使用する	プロジェクトコマンドでは必ず --owner @me または --owner org-name を指定する
CI アーティファクトを手動でダウンロードする	gh run download <run-id> を使用して、アーティファクトをプログラムでダウンロードする
スクリプトで --json を使用しない	--json field1,field2 と --jq を追加して、機械可読形式で出力する
--delete-branch を使わずにマージする	マージ後のクリーンアップには gh pr merge --squash --delete-branch を使用する
-f フィールドを指定せずに gh api の POST を実行する	文字列フィールドには -f key=value、型付きフィールドには -F を使用する

委任

• リポジトリを横断してコードパターンや issue を検索する：Explore エージェントで gh search code と gh search issues を使用します
• 複数ステップのリリースワークフローを自動化する：Task エージェントでブランチ作成、PR のマージ、リリース公開を調整します
• リポジトリの構造とアクセス制御を計画する：Plan エージェントでチームの権限、ブランチ保護、ワークフローのアーキテクチャを設計します

参考資料

• リポジトリと認証 -- 認証、リポジトリ管理、設定、拡張機能、エイリアス
• イシュー -- イシューの作成・読み取り・更新・削除、ラベル、割り当て、ピン留め、移管、開発ブランチ
• プルリクエスト -- PR の作成、レビュー、マージ、チェックアウト、チェック、差分、自動マージ
• Actions -- ワークフロー実行、手動トリガー、シークレット、変数、キャッシュ、アーティファクトのダウンロード
• リリースと検索 -- リリース、アテステーションの検証、検索、Gist、SSH/GPG キー
• プロジェクトと API -- Projects v2 の管理、REST API、GraphQL API、ルールセット、ステータス