The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
gh（GitHub CLI）を使えば、ブラウザーを開かずにGitHub Actionsのワークフロー確認、手動実行、実行状況の監視、ログ確認、キャンセル、再実行、アーティファクト取得までターミナルで行えます。
この記事では、2021年公開のGitHub公式ブログ記事を、現在のGitHub CLIのコマンド体系と認証・セキュリティ上の注意点に合わせて整理します。
GitHub CLIでできること
GitHub CLIは、Gitそのものを置き換えるツールではありません。GitHub上のプルリクエスト、Issue、リポジトリ、Actionsなどをコマンドラインから操作するための公式CLIです。macOS、Windows、Linuxで利用でき、GitHub.comに加えてGitHub Enterprise Cloudや、対応するGitHub Enterprise Server環境でも使えます。
| コマンド | 対象 | 主な用途 |
|---|---|---|
gh workflow |
ワークフロー定義 | 一覧、内容確認、有効化・無効化、手動実行 |
gh run |
個別の実行 | 履歴、状態、ログ、監視、キャンセル、再実行、削除、成果物取得 |
公式マニュアルはgh workflowとgh runで確認できます。
#1 Best Overall
1. GitHub CLIをインストールする
macOSではHomebrewを使えます。
brew install ghWindowsではWindows Package Managerを使えます。
winget install --id GitHub.cliLinuxではディストリビューションの公式パッケージ、またはGitHub CLIのリリースバイナリを利用してください。OS別の手順はGitHub CLI公式リポジトリのインストール案内を確認するのが安全です。
インストール後、バージョンを確認します。
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11gh --versionGitHub ActionsのホステッドランナーにもGitHub CLIはプリインストールされていますが、環境上のバージョンが固定されているとは限りません。スクリプトの再現性や既知の修正を重視する場合は、使用バージョンを明示的に管理してください。最新リリースは公式リリースページで確認できます。
2. 認証する
通常のローカル環境では、次のコマンドを実行します。
gh auth loginログイン後、認証状態を確認します。
gh auth statusGitHub Enterprise Serverを利用する場合はホスト名を指定します。
gh auth login --hostname github.example.com対象リポジトリを閲覧・操作できる権限が必要です。ログインできても、Actionsの実行、キャンセル、再実行などが許可されるとは限りません。
自動化やCIから使う場合は、トークンをコマンドライン引数に直接書かず、GH_TOKEN環境変数として渡します。GitHub Actions内では、必要最小限の権限を設定したGITHUB_TOKENを使うのが基本です。
steps:
- run: gh issue comment "$ISSUE" --body "Thank you for opening this issue!"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ISSUE: ${{ github.event.issue.html_url }}GitHub Actions内でのCLI利用についてはGitHub公式ドキュメントも確認してください。トークンをシェル履歴、標準出力、Actionsログへ出力しないよう注意します。
3. 対象リポジトリを指定する
対象リポジトリ内でコマンドを実行すれば、通常は現在のリポジトリが使われます。別のリポジトリを操作するときは--repoまたは-Rを指定します。
gh workflow list --repo OWNER/REPO
gh run list --repo OWNER/REPOEnterprise Serverではホスト名を含む形式を使います。
gh run list --repo github.example.com/OWNER/REPO4. ワークフローを確認する
ワークフローの一覧を表示します。
gh workflow list無効化されたものも含める場合は--allを付けます。
gh workflow list --allスクリプトで扱いやすいJSON形式も利用できます。
gh workflow list --json id,name,state,path特定ワークフローの概要を表示します。
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →gh workflow view build.ymlYAMLの内容を確認する場合は--yamlを付けます。
gh workflow view build.yml --yaml特定ブランチやタグ上の定義を確認することもできます。
gh workflow view build.yml --ref feature-branch定義をブラウザーで開く場合は--webを使います。コマンドのオプションはCLIのバージョンで変わる可能性があるため、必要に応じて次も確認してください。
gh workflow list --help
gh workflow view --help5. ワークフローを有効化・無効化する
gh workflow disable build.yml
gh workflow enable build.yml無効化はワークフローファイルを削除する操作ではなく、GitHub Actions上でそのワークフローを無効にする操作です。対象リポジトリとファイル名を確認してから実行してください。
Recommended Free Tools
6. ターミナルから手動実行する
gh workflow runで手動実行するには、ワークフローにworkflow_dispatchトリガーが必要です。
name: Build
on:
workflow_dispatch:
inputs:
environment:
description: "Deploy environment"
required: true
default: "staging"
type: choice
options:
- staging
- productionワークフローを実行します。
gh workflow run build.ymlブランチやタグを明示する場合は--refを使います。
gh workflow run build.yml --ref feature-branch入力値は--field、または短縮形の-fで渡せます。
gh workflow run build.yml
--ref main
-f environment=stagingJSONを標準入力から渡す方法もあります。
Free tools Windows power users keep installed
One-click scans. No signup required.
echo '{"environment":"staging"}' | gh workflow run build.yml --json実行できない場合は、次を確認します。
on.workflow_dispatchが定義されているか- 入力名がYAMLの
inputsと完全に一致しているか - 対象ブランチにワークフローファイルが存在するか
- Actionsの実行権限があるか
--refを省略すると、意図したブランチではなく既定ブランチ側の定義で実行されることがあります。特にデプロイ用途ではブランチやタグを明示してください。productionを選べる場合でも、GitHub Environmentsの承認、ブランチ保護、デプロイ保護ルールが別途適用される可能性があります。
詳細はgh workflow runの公式マニュアルを参照してください。
7. 実行履歴を一覧表示する
gh run list取得件数を増やしたり、条件を絞り込んだりできます。
gh run list --limit 50
gh run list --workflow build.yml
gh run list --branch main
gh run list --status failure
gh run list --status in_progress
gh run list --event workflow_dispatch
gh run list --commit COMMIT_SHAJSONとjqを組み合わせると、必要な項目だけを表示できます。
gh run list
--limit 20
--json databaseId,status,conclusion,workflowName,headBranch,createdAt,url
--jq '.[] | [.databaseId, .status, .conclusion, .workflowName, .headBranch, .url] | @tsv'一覧に目的の実行が出ない場合は、--all、--workflow、--branch、--event、--repoの指定を見直してください。手動実行直後は一覧に反映されるまで遅延する場合もあります。
8. 実行結果とログを確認する
実行IDを指定して概要を表示します。
gh run view RUN_IDジョブとステップを詳しく表示するには--verboseを使います。
gh run view RUN_ID --verbose全ログ、失敗したステップだけのログ、特定ジョブのログは次のように取得できます。
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
gh run view RUN_ID --log
gh run view RUN_ID --log-failed
gh run view RUN_ID --job JOB_ID --logシェルスクリプトで成功・失敗を判定するには--exit-statusが便利です。
if gh run view RUN_ID --exit-status >/dev/null; then
echo "workflow succeeded"
else
echo "workflow failed"
gh run view RUN_ID --log-failed
exit 1
fi--webを付ければブラウザーで開けます。
gh run view RUN_ID --webログには機密情報が含まれる可能性があります。貼り付けや保存の前に、トークン、パスワード、内部URLなどが出ていないか確認してください。また、Actionsログ表示に関するターミナルエスケープシーケンスの脆弱性修正がGitHub CLI 2.92.0で行われています。古いCLIで--logや--log-failedを使わず、公式リリース情報を確認して更新してください。
9. 実行を監視する
gh run watch RUN_ID失敗時に終了コードを返し、出力を簡潔にする例です。
gh run watch RUN_ID --exit-status --compact更新間隔を指定することもできます。既定の更新間隔は3秒です。
gh run watch RUN_ID --interval 10手動実行から監視までの基本的な流れは次のとおりです。
gh workflow run build.yml --ref main
gh run list --workflow build.yml --limit 1
gh run watch RUN_ID --exit-status実行直後は一覧への反映が遅れる場合があるため、表示されたURLや実行ID、または現在のCLIの出力形式を確認してから監視してください。
10. キャンセル・再実行する
実行をキャンセルします。
gh run cancel RUN_ID通常のキャンセルで停止しない場合は--forceを使えます。
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minutegh run cancel RUN_ID --forceただし、すでに外部システムへ加えた変更は自動的に元へ戻りません。デプロイやデータ更新の途中で強制キャンセルする場合は、後続状態を確認してください。
実行全体を再実行するには次を使います。
gh run rerun RUN_ID失敗したジョブだけ、または特定ジョブだけを再実行できます。
gh run rerun RUN_ID --failed
gh run rerun RUN_ID --job JOB_IDデバッグログを有効にして再実行する場合は--debugを付けます。
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsgh run rerun RUN_ID --debug再実行は一時的なネットワーク障害などの切り分けには有効ですが、根本原因を直す代わりにはなりません。外部サービスへの重複登録やデプロイが発生する可能性があるため、元のコミット、ワークフロー定義、ジョブの副作用を確認してから実行します。
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.11. アーティファクトをダウンロードする
実行に紐づくアーティファクトを対話的に選択して取得できます。
gh run download RUN_ID名前、保存先、パターンを指定する例です。
gh run download RUN_ID --name tps-report
gh run download RUN_ID --dir ./artifacts
gh run download RUN_ID --pattern "*.zip"CIの成果物をローカルで確認するときは、保存先を明示して後続処理が扱いやすい状態にしておくと便利です。
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
12. 実行履歴を削除する
gh run delete RUN_ID削除するとログやアーティファクト、トラブルシュートに必要な履歴も失われる可能性があります。組織の保管・監査要件や保持ポリシーを確認してから実行してください。
13. シェルスクリプトに組み込むときの要点
自動化では、表示用のテキストを解析するより、JSON出力と終了コードを使うほうが安定します。
gh run list
--workflow build.yml
--limit 10
--json databaseId,status,conclusion,url
--jq '.[] | [.databaseId, .status, .conclusion, .url] | @tsv'処理結果の判定には--exit-statusを利用します。
gh run view RUN_ID --exit-statusただし、実行IDの取得と一覧反映には遅延があり得ます。実運用では、対象リポジトリ、ワークフロー、ブランチ、コミットを明示し、別の実行を誤って監視しないようにします。
14. GitHub CLIでできないこと
GitHub CLIは主にGitHub上で動くActionsを操作するツールです。次の用途はghだけでは解決できません。
- GitHub Actionsを本番と同じ条件で完全にローカル再現する
- GitHubホステッドランナーを使わずに同じワークフローを実行する
- YAMLの動作をGitHubの実行環境と完全一致させて検証する
- GitHubの請求やActionsの利用料金を回避する
- ワークフローの失敗原因を自動修正する
ローカル実行を試したい場合は、actが候補です。actはワークフローを読み取り、Docker APIを使ってイメージやコンテナを実行します。ただし、GitHubホステッドランナーのOS、権限、サービス、Secrets、すべてのアクションの挙動を完全に再現するものではありません。
GitHub CLI拡張として導入する方法もあります。
gh extension install nektos/gh-act第三者拡張を使うときは、ソースコード、要求権限、リリース状況、メンテナンス状況を確認してください。
Recommended Free Tools
| 目的 | 適した選択肢 |
|---|---|
| GitHub上の実行を起動・監視・再実行 | gh |
| GitHub上のログ・アーティファクト取得 | gh |
| ワークフローをローカルで試す | act |
| GitHubの実行環境を完全再現する | どちらも保証しない |
よくあるエラーと対処
| 症状 | 主な原因 | 確認・対処 |
|---|---|---|
gh: command not found |
未インストール、PATH未設定 | gh --versionと公式インストール手順を確認 |
| 認証エラー | 未ログイン、期限切れ、権限不足 | gh auth status、必要ならgh auth login |
| リポジトリが見つからない | 対象リポジトリの指定ミス | --repo OWNER/REPOを明示 |
| 手動実行できない | workflow_dispatchがない |
ワークフローYAMLのon.workflow_dispatchを確認 |
| 入力値エラー | 入力名の不一致 | inputsと-f key=valueを照合 |
| 実行が一覧に出ない | 反映遅延、ブランチ違い、Actions無効 | gh workflow list --all、gh run list、--refを確認 |
| ログが見えない | 権限不足、実行中、保持期間切れ | gh run view RUN_IDと実行状態、権限を確認 |
| 再実行できない | 権限、状態、組織ポリシー | 実行の詳細とリポジトリの権限を確認 |
actが動かない |
Docker未起動、環境差異、外部サービス依存 | Docker、イメージ、Secrets、依存サービスを確認 |
まとめ
gh workflowはワークフロー定義を扱い、gh runは個別の実行を扱います。この違いを押さえると、ターミナルからActionsを効率よく操作できます。
Quick Recap
- 一覧と定義確認は
gh workflow list、gh workflow view - 手動実行は
gh workflow run。事前にworkflow_dispatchが必要 - 履歴・ログ・監視は
gh run list、gh run view、gh run watch - 失敗判定には
--exit-status、失敗箇所の確認には--log-failed - キャンセル、再実行、削除は副作用や履歴消失の可能性を確認してから実行
- ローカル実行はGitHub CLIの機能ではなく、必要に応じて
actを検討
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
