GitHub CLI (gh)
コマンドラインからGitHubを操作:リポジトリ、リリース、Issue、PR、ディスカッション、検索、コードレビュー、Actions。
gh 2.95.0 で検証済み。
エージェントガイドライン
- 既知のリモートファイルやディレクトリについては、
gh repo read-file/gh repo read-dirを使用します(gh2.95 ではプレビュー機能)。古いghバージョンやAPI限定の場合は、APIパターン にある contents API のフォールバックを使用します。 - タスクで複数ファイルにまたがる検索や、パスが事前にわからないコードの探索が必要な場合は、一時ディレクトリにクローンし(
gh repo clone owner/repo <temp-dir> -- --depth 1)、ローカルのファイル読み取り・検索ツールを使用します。 - 閲覧・表示には
--jsonよりもデフォルトのテキスト出力を優先します。これはトークン効率が良いためです。プログラムで特定のフィールドを抽出する場合のみ--jsonと--jqを使用します。サポートされているフィールドを確認するには、フィールドリストなしで--jsonを指定してコマンドを実行し、必要なフィールドだけをリクエストします。 - ログや差分を表示する際は、完全な内容を取得する前に、まず出力範囲を指定します(例:
--name-only、--log-failed)。 - クローンしたリポジトリ内で作業する場合、
--repoフラグは不要です。デフォルトでカレントディレクトリのリポジトリが使用されます。gh apiを使用する場合は、明示的なパス(repos/OWNER/REPO/...)を使用するか、GH_REPO環境変数を設定します。 - このスキルは上記のワークフローをカバーしています。必要なフラグやフィールドがここにない場合、コマンドが不明または変更されたフラグで失敗する場合、コマンドがプレビューとマークされている場合は、該当コマンドのヘルプを確認してください(例:
gh pr diff --help)。
安全性
- 書き込み操作(
create、edit、comment、review、close、merge、delete、rerun、run cancel、workflow run/enable/disable、ディスカッションの変更)はGitHubの状態を変更します。実行する前に、特に所有していないリポジトリでは、ユーザーに確認してください。 gh apiと--method POST/PUT/PATCH/DELETEは書き込みリクエストを送信します。エンドポイントとペイロードを再確認してください。デフォルトのメソッドはGET(安全)ですが、-f/-Fパラメーターを追加するとデフォルトがPOSTに変わります。- 破壊的操作(
delete、close、merge --admin)は元に戻せない場合があります。明示的なユーザー確認が必要です。
前提条件
コマンドを実行する前に、gh がインストールされ認証されていることを確認します:
gh --version
gh auth status
認証されていない場合は、ユーザーに gh auth login を案内します。
共通フラグ
これらのフラグは多くのコマンドグループで使用できますが、コマンドによってサポート状況は異なります:
--repo OWNER/REPO-- 別のリポジトリを対象にする(デフォルト:カレントディレクトリのリポジトリ)。完全なURLも受け付けます。--json FIELDS-- 指定されたフィールドをJSON形式で出力する。値を指定せずに実行すると、利用可能なフィールドが一覧表示されます。--jq EXPRESSION-- jq構文を使用してJSON出力をフィルターする。--jsonが必要です。--template STRING-- Goテンプレートを使用してJSON出力をフォーマットする(--jqの代わり)。--web-- ターミナル表示ではなくブラウザでリソースを開く。--limit N-- リストコマンドの最大結果数(デフォルトは通常30)。
リポジトリ
表示
リポジトリの説明、README、スター、言語の内訳、その他のメタデータを表示します。
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
クローン
リポジトリをローカルにクローンします。自動的にリモートを設定し、フォークの場合はupstreamリモートを設定します。
gh repo clone owner/repo [target-directory]
リモートリポジトリの内容を読み取る
既知のファイルやディレクトリを素早く読み取るには、リポジトリ読み取りコマンドを使用します(gh 2.95 ではプレビュー):
# 既知のファイル
gh repo read-file src/main.py --repo owner/repo --ref main
# 既知のディレクトリ
gh repo read-dir src --repo owner/repo --ref main
# 古いghバージョン用のフォールバック
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
出力形式、ファイルサイズ制限、ディレクトリ一覧の注意事項については、APIパターン を参照してください。複数ファイルの探索には、代わりにクローンしてください(エージェントガイドライン参照)。
リポジトリ一覧
ユーザーまたは組織が所有するリポジトリを、言語や可視性フィルターを指定して一覧表示します。
gh repo list owner --limit 30
リリース
一覧
リポジトリのリリースを、作成日順(新しい順)で一覧表示します。デフォルトでは、プレリリースやドラフトを含むすべてのリリースが表示されます。
gh release list --repo owner/repo --limit 10
フラグ:
--exclude-pre-releases-- プレリリースを除外--exclude-drafts-- ドラフトを除外
主要なJSONフィールド:tagName、name、publishedAt、isLatest、isDraft、isPrerelease、isImmutable
表示(変更履歴、アセット)
リリースの変更履歴本文、タグ、アセット、メタデータを表示します。タグを省略すると最新リリースが表示されます。
gh release view --repo owner/repo # 最新リリース
gh release view v1.2.0 --repo owner/repo # 特定のタグ
gh release view v1.2.0 --json tagName,body,assets,publishedAt
主要なJSONフィールド:tagName、name、body、assets、author、publishedAt、isDraft、isPrerelease、isImmutable、url
Issue
一覧
リポジトリのIssueを、状態、ラベル、アサイン、または検索クエリでフィルターして一覧表示します。デフォルトではオープンなIssueのみ表示します。
gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"
フラグ:
--state VALUE--open(デフォルト)、closed、all--label NAME-- ラベルでフィルター(複数指定可)--assignee LOGIN-- アサインでフィルター(自分自身は@me)--search QUERY-- GitHub検索構文
主要なJSONフィールド:number、title、state、stateReason、author、labels、assignees、createdAt、updatedAt、url
表示
Issueのタイトル、本文、ラベル、アサイン、ステータスを表示します。--comments を使用すると、コメントスレッド全体を含めます。
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
作成
タイトル、本文、ラベル、アサインを指定して新しいIssueを作成します。
gh issue create --title "Bug: description" --body "Details..." --label bug --assignee user1
編集
Issueのタイトル、本文、ラベル、アサイン、マイルストーンを更新します。すべてのフラグは1回の呼び出しで組み合わせ可能です。
フラグ:
--title TEXT/--body TEXT-- タイトルまたは本文を更新--add-label NAME/--remove-label NAME-- ラベルを変更--add-assignee LOGIN/--remove-assignee LOGIN-- アサインを変更--milestone NAME/--remove-milestone-- マイルストーンを設定/削除
コメント
既存のIssueにコメントを追加します。
gh issue comment 123 --body "Comment text"
クローズ / 再オープン
Issueをクローズまたは再オープンします。オプションでクローズ理由を指定し、コメントを残せます。
gh issue close 123 --comment "Fixed in PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
クローズ理由:completed(デフォルト)、not planned、duplicate。
ステータス
自分に関連するIssueの概要を表示します:自分にアサインされたもの、自分に言及しているもの、自分が作成したもの。
gh issue status
Issueの種類、サブIssue、親子関係、ブロッキング依存関係、およびそれらのJSONフィールドについては(サポートされているGitHubホストが必要です)、Issueリファレンス を参照してください。
プルリクエスト
これらのコマンドを使用してPRを表示・調査します。作成、マージ、レビュー、管理については、プルリクエストリファレンス を参照してください。
一覧
リポジトリのプルリクエストを、状態、作成者、ラベル、または検索クエリでフィルターして一覧表示します。デフォルトではオープンなPRのみ表示します。
gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot
フラグ:
--state VALUE--open(デフォルト)、closed、merged、all--draft-- ドラフト状態でフィルター--author LOGIN/--assignee LOGIN-- 作成者またはアサインでフィルター--label NAME-- ラベルでフィルター--search QUERY-- GitHub検索構文--app NAME-- GitHubアプリの作成者でフィルター(例:dependabot)
主要なJSONフィールド:number、title、state、author、headRefName、baseRefName、labels、reviewDecision、isDraft、statusCheckRollup、files、commits、reviews、url
表示
PRのタイトル、本文、レビューステータス、チェック、その他のメタデータを表示します。引数なしの場合は、現在のブランチのPRを表示します。--comments を使用すると、コメントスレッドを含めます。
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
ステータス
自分に関連するPRの概要を表示します:現在のブランチのPR、自分が作成したPR、自分のレビューがリクエストされているPR。
gh pr status
ディスカッション
リポジトリディスカッションには gh discussion を使用します(gh 2.94 でプレビュー)。コマンドセットはプレビューであるため、読み取りコマンドから始め、--help でフラグを確認します:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
作成、編集、コメント、返信スレッド、JSON出力形式、GraphQLフォールバックパターンについては、ディスカッションリファレンス を参照してください。
検索
GitHub全体でIssue、PR、コード、コミット、リポジトリを検索します。単一リポジトリの場合は gh issue list / gh pr list を使用し、リポジトリ間やオーナー全体のクエリには gh search ... を使用します。
完全な検索クエリ構文については、GitHub検索ドキュメント を参照してください。各サブコマンド固有のフラグについては、gh search <subcommand> --help を実行します。
レート制限: 検索APIはコアAPIよりも厳しいレート制限があります。コード検索が最も制限が厳しく(認証済みで約10/分;認証必須)、他の検索コマンドは認証済みで約30/分、未認証で約10/分です。現在のクォータは gh api rate_limit --jq '.resources | {search, code_search}' で確認できます。
代わりにクローンする場合: APIを使用する代わりにクローンすべき状況については、エージェントガイドラインを参照してください。
ボットとアプリ: DependabotなどのGitHubアプリ作成者の場合、--app dependabot を使用します。--author dependabot はユーザーアカウントをフィルターし、アプリ作成者はフィルターしません。
偵察: 馴染みのないリポジトリを検索する際は、まず主要言語を確認して正しい --extension と --language 値を選択します:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
Issue
キーワード、ラベル、状態、またはGitHub検索構文を使用して、リポジトリ間でIssueを検索します。
gh search issues "error handling" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo
主要フラグ:--repo、--owner、--state、--label、--assignee、--author、--app、--involves、--comments、--match、--sort、--include-prs。
PR
リポジトリ間でプルリクエストを検索します。作成者、レビューステータス、マージ状態、ドラフト状態によるフィルタリングをサポートします。
gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo
主要フラグ:--repo、--owner、--state、--merged、--draft、--author、--assignee、--app、--label、--review、--review-requested、--base、--head、--checks、--sort。
コード
GitHubリポジトリ間でファイルの内容を検索します。一致する行のみが返されます(行番号、周辺コンテキストはなし)。パターンを含むファイルの特定に便利ですが、コードロジックを理解するにはファイル読み取りやリポジトリクローンが必要です。
制限事項: レガシー検索エンジンを使用しています(結果がgithub.comと一致しない場合があります)。デフォルトブランチのみが検索対象です。384KB未満のファイルのみがインデックス化されます。すべてのクエリには少なくとも1つの検索語を含める必要があります(--extension ts のような修飾語のみの検索は失敗します)。--sort や --order はサポートせず、結果は常に関連性順にランク付けされます。
gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
主要フラグ:--repo、--owner、--extension、--filename、--language、--match、--size。
主要なJSONフィールド:path、repository、sha、textMatches、url。
textMatches フィールドは、文字単位の一致位置を含むフラグメントコンテキストを提供します。デフォルトのテキスト出力よりも多くのコンテキストが必要な場合は、--json path,textMatches を使用します。
コミット
コミットメッセージテキスト、作成者、コミッター日付、またはハッシュで検索します。
gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
主要フラグ:--repo、--owner、--author、--committer、--author-date、--committer-date、--author-name、--author-email、--hash、--merge、--sort。
リポジトリ
キーワード、言語、トピック、スター数、ライセンス、またはオーナーでリポジトリを検索します。注意:このサブコマンドでは --repo は使用できません。代わりに --owner を使用してフィルターします。
gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
主要フラグ:--owner、--language、--topic、--stars、--forks、--license、--created、--updated、--match、--sort、--include-forks、--visibility。
修飾語の除外(ハイフンプレフィックス)
-label:bug のような除外を含む検索クエリは、シェルのフラグ解釈を避けるために特別な構文が必要です。すべてのフラグ(例:--limit)は -- の前に配置する必要があります。-- の後はすべて検索クエリテキストとして解釈されます:
# Unix系シェル
gh search issues -- "my query -label:bug"
# PowerShell
gh --% search issues -- "my query -label:bug"