github

GitHub

GitHub のすべての操作には gh CLI を使用します。構造化された解析可能な出力には、--json と --jq の併用を優先してください。設定済みのリモートを持つ Git リポジトリ内にいない場合は、--repo owner/repo を使用してください。任意のリソースをブラウザーで開くには、--web を使用してください。

前提条件と認証

インストール

プラットフォーム	コマンド
macOS	brew install gh
Debian/Ubuntu	sudo apt install gh
Windows	winget install GitHub.cli

認証

gh auth login           # interactive OAuth login
gh auth status          # check current auth and active account

必要な OAuth スコープ

スコープ	アクセス権限
repo	プライベートリポジトリ、課題、PR、コミット、ステータス
read:org	組織への所属、チーム一覧
workflow	GitHub Actions ワークフローの実行と管理
gist	gist の作成と管理
delete_repo	リポジトリの削除（デフォルトでは付与されません）
admin:org	組織の設定、チーム、メンバーの管理
project	ProjectV2 ボードへの読み書きアクセス

最初から再認証せずに、不足しているスコープを追加します。

gh auth refresh --scopes repo,read:org,workflow

---

リファレンスのルーティング

ユーザーの意図	読み込むファイル
課題の作成／一覧表示／表示／編集／クローズ、コメントの追加	references/issues.md
プルリクエストの作成／一覧表示／表示／レビュー／マージ／編集／クローズ	references/pull-requests.md
実行の一覧表示、ログの表示、ワークフローの実行／再実行／監視、アーティファクト	references/ci-actions.md
リポジトリの作成／フォーク／クローン／表示／編集／アーカイブ／削除	references/repos.md
リリースの作成／一覧表示／表示／編集／アップロード／削除	references/releases.md
リポジトリ、課題、PR、コード、コミットの検索	references/search.md
gh api による REST／GraphQL の生データ、ページネーション、レート制限	references/api.md
GraphQL のコストモデル、一括クエリ、ミューテーション、レート制限	references/graphql-queries.md
複数ステップのワークフローレシピ（PR のライフサイクル、CI のトリアージ、リリース）	references/automation-workflows.md
gist の作成／一覧表示／表示／編集／削除	references/gists.md
組織、チーム、メンバーの一覧表示	references/orgs.md

ワークフローのパターン

1. 上のルーティング表からユーザーの意図を特定します。
2. コマンドの構文と例について、対応する references/<file>.md を読み込みます。
3. 必要に応じて --repo owner/repo と --json／--jq を指定して、gh コマンドを実行します。
4. エラーが発生した場合は、下のエラー処理表を確認します。

---

エラー処理

エラー	原因	解決方法
HTTP 401 Unauthorized	トークンの有効期限が切れているか、取り消されています	gh auth login を実行して再認証します
HTTP 403 Forbidden	権限が不足しているか、レート制限に達しています	スコープは gh auth status で確認し、gh api rate_limit も確認します
HTTP 404 Not Found	リポジトリが存在しない、repo スコープなしで非公開になっている、またはリソースが削除されています	リポジトリ名を確認し、gh auth refresh --scopes repo を実行します
HTTP 422 Unprocessable Entity	ペイロードが無効です。必須フィールドがないか、検証エラーがあります	リクエスト本文のフィールドが API スキーマに適合していることを確認します
HTTP 429 Too Many Requests	REST のレート制限を超過しています（認証済みの場合、1 時間あたり 5000 リクエスト）	X-RateLimit-Reset のタイムスタンプまで待機し、リクエスト頻度を下げます
GraphQL rate limit exceeded	1 時間あたり 5000 ポイントを超えて使用しています	クエリの複雑さを下げるか、待機します。references/graphql-queries.md を参照してください
"no git remotes found"	--repo を指定せずに、Git リポジトリ外で gh を実行しています	コマンドに --repo owner/repo を追加します
Insufficient OAuth scopes	トークンに操作に必要なスコープがありません	gh auth refresh --scopes scope1,scope2 を実行します
Duplicate issue/PR title	実際のエラーではありません。GitHub では重複が許可されていますが、作成前に確認してください	まず gh issue list または gh pr list で検索します
Archived repo blocks writes	リポジトリがアーカイブされているため、書き込み操作がすべて失敗します	gh repo edit owner/repo --archived=false でアーカイブを解除するか、別のリポジトリを使用します

デバッグログを有効にすると、未加工の HTTP リクエストとレスポンスを確認できます。

GH_DEBUG=api gh pr list --repo owner/repo

---

調整ルール

1. テキスト出力の解析よりも --json を優先します。 テキスト出力の形式は gh のバージョンによって安定していません。機械可読な出力を得るには、常に --json field1,field2 を使用します。
2. 処理前に --jq で出力を最小限にします。 大きな JSON データを外部ツールに渡すのではなく、データの取得元でフィルタリングします。--jq はサーバー側で実行され、転送データを削減します。
3. 生の API よりも高レベルのコマンドを優先します。 gh api repos/.../issues -X POST ではなく、gh issue create を使用します。高レベルのコマンドでは、認証、ページネーション、エラー形式の処理が自動的に行われます。
4. Git ディレクトリの外では、常に --repo を使用します。 スクリプトや CI 環境で、暗黙的なリポジトリ検出に頼らないでください。常に --repo owner/repo を明示的に指定します。
5. GraphQL はネストされたデータや一括データにのみ使用します。 単一リソースの取得や、単純なペイロードを使った変更には、REST のほうが記述しやすく、デバッグも容易で、レート制限下でも予測しやすいためです。

---

制限事項

• ネットワークが必要 — すべての gh コマンドでインターネット接続が必要です。オフラインモードはありません。
• GraphQL のポイント上限 — 認証済みユーザーは 1 時間あたり 5000 ポイントです。first／last の値が大きい複雑なクエリは、より速くポイントを消費します。references/graphql-queries.md を参照してください。
• シークレットは書き込み専用 — gh secret set は使用できますが、gh secret get はありません。作成後にシークレットの値を取得することはできません。
• 組織の管理者操作 — 組織の設定、チーム、SAML の管理には admin:org スコープが必要ですが、これはデフォルトでは付与されません。
• アーティファクトの保持期間 — ワークフローのアーティファクトは、デフォルトで 90 日間保持されます。期限切れのアーティファクトはダウンロードできません。