gh-cli

GitHub CLI (gh)

コマンドラインから実行できる GitHub の作業では、リポジトリの調査、イシューやプルリクエストの管理、Actions の実行、リリース、gist、認証済みの GitHub API 呼び出しなどに、まず gh を使用してください。

正確なフラグや現在の動作を確認するには、gh help、gh <command> --help を実行するか、公式の GitHub CLI マニュアルを参照してください。

運用の基本方針

• GitHub の操作では、特に出力をコピー、フィルタリング、スクリプトで処理する必要がある場合、場当たり的なブラウザー操作より gh を優先してください。
• 変更を加える前に状況を確認してください。コンテキスト、リポジトリ、ブランチ、またはアカウントが不確かな場合は、まず読み取り専用のコマンドを実行してください。
• 対象リポジトリのチェックアウト内で作業していない場合は、--repo OWNER/REPO を使って対象リポジトリを明示してください。
• 人間向けのテーブルを解析するのではなく、構造化された出力を得るために --json と --jq を使用してください。
• 自動化では対話型プロンプトを避けてください。コマンドのヘルプを確認し、操作が安全であることを確認したうえで、--body-file、--title、--label、--assignee、--confirm、--yes などのフラグを使用してください。
• 破壊的な操作は高リスクとして扱ってください。削除、クローズ、マージ、アーカイブ、リリースの削除、シークレットの更新、ワークフローのキャンセル、権限の変更には、追加の確認が必要です。

初期確認

gh を使用する前に、基本事項を確認してください。

gh --version
gh auth status
git remote -v
gh repo view --json nameWithOwner,defaultBranchRef,url

コンテキストの確認に役立つコマンド：

gh status
gh repo view --web
gh browse --no-browser
gh config list

GitHub Enterprise または現在のものではないリポジトリでは、gh help に記載された適切なホスト名とリポジトリのフラグを使用してください。

一般的なワークフロー

リポジトリ

gh repo view OWNER/REPO
gh repo clone OWNER/REPO
gh repo fork OWNER/REPO --clone=false
gh repo sync OWNER/REPO --branch BRANCH
gh repo list OWNER --limit 100 --json name,visibility,url

イシュー

gh issue list --state open --limit 50
gh issue view NUMBER --comments
gh issue create --title "Title" --body-file body.md
gh issue comment NUMBER --body-file comment.md
gh issue edit NUMBER --add-label label --add-assignee @me

プルリクエスト

gh pr status
gh pr list --state open --limit 50
gh pr view NUMBER --comments --files
gh pr diff NUMBER
gh pr checkout NUMBER
gh pr create --fill
gh pr review NUMBER --comment --body-file review.md
gh pr checks NUMBER --watch

PR を作成または更新する前に、git status --short、git branch --show-current、git log --oneline --decorate -n 10 を使って、ローカルの git の状態を確認してください。

Actions とワークフロー

gh run list --limit 20
gh run view RUN_ID --log
gh run watch RUN_ID
gh workflow list
gh workflow run WORKFLOW --ref BRANCH

workflow-dispatch コマンドを使用するのは、対象ブランチ、ワークフロー名、必須の入力値を確認した後にしてください。

リリース

gh release list
gh release view TAG
gh release create TAG --notes-file notes.md
gh release upload TAG path/to/asset

リリースを公開または編集する前に、タグ、生成されたリリースノート、アセットを確認してください。

GitHub API

gh に専用コマンドがない場合や、GraphQL または REST エンドポイントを直接使う必要がある場合は、gh api を使用してください。

gh api repos/OWNER/REPO
gh api graphql -f query='query { viewer { login } }'
gh api --paginate repos/OWNER/REPO/issues

フィルタリングには --jq を優先し、エンドポイントが複数ページを返す可能性がある場合に限り --paginate を使用してください。

出力の取り扱い

• スクリプトでは、安定した機械処理向けの出力を優先してください。

  gh pr view NUMBER --json title,author,state,mergeable --jq '{title, author: .author.login, state, mergeable}'
  

• Markdown の本文は、一時ファイルまたは既存のファイルに書き込み、--body-file／--notes-file を指定してください。長文に対する複雑なシェルのクォートは避けてください。

• 出力にシークレット、トークン、非公開 URL、またはユーザーデータが含まれる可能性がある場合は、そのまま貼り付けず、要約してください。

認証と権限

gh auth status を使って、アクティブなアカウントとホストを確認してください。スコープ不足でコマンドが失敗した場合は、エラーを確認してから、必要なスコープについて公式ヘルプを参照してください。一般的な対処方法には、対話型の利用時に gh auth refresh を実行する方法や、自動化で GH_TOKEN を設定する方法があります。

タスクで明示的に必要とされ、出力が公開されない場合を除き、gh auth token でトークンを表示しないでください。

gh を使用しない場合

• コミット履歴、blame、ブランチ操作、ステージング、リベース、ローカルの差分には、ローカルの git を使用してください。
• ローカルコードの理解には、ファイルを直接読み取るか、リポジトリ内を検索してください。
• UI でしか利用できない機能、目視確認、または gh では対応できない認証フローが必要な場合にのみ、ブラウザーを使用してください。