【入門編】GitHub ActionsのAPIを叩いてワークフローを制御！GitHub CLI (gh) を使った高度な自動化術 – バージョン管理・CI/CD活用バイブル

皆さん、こんにちは！最前線の開発現場でCI/CDの自動化に情熱を燃やす先輩エンジニアです。

GitHub Actions、便利ですよね。コードをプッシュするだけでテストが走り、デプロイまで自動化してくれる。もはや現代の開発に欠かせないツールです。でも、「ブラウザを開いて状況を確認して、手動で実行して…」と、ちょっとした操作のためにマウスに手を伸ばしていませんか？

今回お話しするのは、その手間を劇的に減らし、日々の作業を「震えるほど」楽にする究極の自動化術の第一歩です。そう、GitHub CLI (gh) を使って、GitHub Actionsをターミナルから自在に操る方法です！

これをマスターすれば、ブラウザを開くことなく、ワークフローの実行状況確認、手動実行、そして詳細なログ取得まで、すべてコマンドラインから完結できるようになります。さらに、シェルスクリプトやcronと組み合わせれば、社内のCI運用を高度に自動化する扉が開きますよ。

さあ、あなたも今日からCLIの力を手に入れて、CI/CDの達人への道を歩み始めましょう！

—

1. GitHub CLI (gh) って何？その役割と魅力

「GitHub CLI (gh)」とは、GitHubが公式に提供しているコマンドラインツールです。ターミナル（コマンドプロンプトやPowerShell）からGitHubの様々な機能を操作できる魔法のようなツールだと思ってください。

普段ブラウザでポチポチとやっている以下の操作、すべて`gh`コマンド一つでできるようになります。

プルリクエストの作成、レビュー、マージ
Issueの作成、コメント、クローズ
リポジトリのクローン、フォーク、設定変更
そして、今回主役となるGitHub Actionsのワークフロー操作！

なぜCLIから操作するのかって？それは、速度、効率、そして何より自動化の可能性が圧倒的に広がるからです。

素早い操作: マウスでのクリックより、キーボードでのコマンド入力の方が圧倒的に速い場面は多いですよね。
スクリプト化: 一連の操作をシェルスクリプトにまとめれば、ワンコマンドで複雑な処理を実行できます。
自動化: cronなどのスケジューラーと組み合わせれば、人間が介在せずに定期的な処理を自動実行できます。

特にCI/CDの文脈では、この「自動化」が肝になります。例えば、「毎日深夜に特定のリポジトリでテストワークフローを動かし、結果をSlackに通知する」といったことが、`gh` CLIを使えば簡単に実現できるようになるんですよ。

2. GitHub CLI (gh) のインストールと初期設定

まずは、`gh` CLIをあなたの環境に導入しましょう。インストールはとても簡単です。

2.1. インストール

お使いのOSに合わせて、以下のいずれかの方法でインストールしてください。

macOSの場合 (Homebrewが推奨)

brew install gh

Linuxの場合 (Debian/Ubuntu)

type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo “deb [arch=$(dpkg –print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main” | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

Windowsの場合 (wingetが推奨)

winget install GitHub.cli

その他のOSや詳細なインストール方法は、[GitHub CLI公式ドキュメント](https://github.com/cli/cli#installation) を参照してください。

2.2. 初期設定（認証）

インストールが完了したら、GitHubアカウントとの認証を行います。これにより、`gh` CLIがあなたのGitHubリポジトリにアクセスできるようになります。

gh auth login

このコマンドを実行すると、以下のような対話形式のプロンプトが表示されます。

1. “What account do you want to log into?”: `GitHub.com` を選択 (通常は `Enter` でOK)
2. “What is your preferred protocol for Git operations?”: `HTTPS` または `SSH` を選択。通常は `HTTPS` で問題ありません。
3. “Authenticate Git with your GitHub credentials?”: `Y` を選択し、Git操作も`gh` CLIで認証できるようにします。
4. “How would you like to authenticate GitHub CLI?”: `Login with a web browser` を選択してください。
5. ブラウザが自動的に開き、GitHubの認証ページが表示されます。「Authorize GitHub CLI」をクリックして認証を完了します。
6. ターミナルに戻ると、認証が成功した旨のメッセージが表示されます。

これで、`gh` CLIを使う準備が整いました！

2.3. ちょっと便利な追加設定（任意だが推奨）

チームで複数のGitHub Organizationを使っている場合、`gh`コマンドを実行するたびに「どのOrganizationですか？」と聞かれることがあります。これを非表示にして、常にデフォルトのOrganizationやカレントディレクトリのリポジトリを優先させたい場合は、以下の設定をしておくと便利です。

gh config set prompt-for-orgs false

これで、よりスムーズに操作できるようになります。

3. GitHub Actionsの基本的なワークフローを用意しよう (HelloWorld)

`gh` CLIでGitHub Actionsを操作する前に、まずは操作対象となる簡単なワークフローを用意しましょう。

あなたのリポジトリのルートディレクトリに、以下のディレクトリとファイルを作成してください。

.github/workflows/hello.yml

`hello.yml` の内容は以下の通りです。

.github/workflows/hello.yml

name: Hello GitHub CLI

このワークフローは、pushイベントだけでなく、
workflow_dispatchトリガーによって手動で実行できるように設定します。
これがCLIからの手動実行に不可欠です！
on:
push:
branches:

main

workflow_dispatch:
inputs:
name:
description: ‘あなたの名前を入力してください’
required: false
default: ‘世界’

jobs:
greet:
runs-on: ubuntu-latest
steps:

name: Checkout repository

uses: actions/checkout@v4

name: Say Hello

run: |
# workflow_dispatchで入力された名前を使用します。
# 入力がなければデフォルトの「世界」を使います。
PERSON_NAME=”${{ github.event.inputs.name || ‘世界’ }}”
echo “こんにちは、${PERSON_NAME}さん！ GitHub ActionsとCLIの世界へようこそ！”
echo “現在時刻: $(date)”
echo “リポジトリ名: ${{ github.repository }}”

ポイント:

`on: workflow_dispatch:` が非常に重要です。これがないと、CLIから手動でワークフローをトリガーできません。
`inputs:` セクションを使うことで、手動実行時に引数を渡せるようになります。今回は「あなたの名前」を入力できるようにしてみました。
`echo` コマンドで簡単なメッセージを表示するだけの、シンプルなワークフローです。これを`main`ブランチにプッシュしておきましょう。

4. `gh` CLIでGitHub Actionsを操作する基礎の基礎

それではいよいよ、`gh` CLIを使ってGitHub Actionsを操作してみましょう。ここが本番ですよ！

前提: 以下のコマンドは、上記の `hello.yml` が存在するリポジトリのルートディレクトリで実行するか、`-R /` オプションでリポジトリを指定して実行してください。

4.1. ワークフローの一覧表示: `gh workflow list`

まずは、リポジトリにどんなワークフローがあるかを確認しましょう。

gh workflow list

実行例:

✓ Checks for a pull request
✓ Deploy to Production
✓ Hello GitHub CLI # <-- これが今回作成したワークフローです `gh workflow list` は、リポジトリ内の `.github/workflows` ディレクトリにあるワークフローファイルの一覧を表示します。`Hello GitHub CLI` が表示されていることを確認してください。

4.2. ワークフローの手動実行 (dispatch): `gh workflow run`

いよいよ、CLIからワークフローを実行してみましょう。`workflow_dispatch`トリガーを設定した恩恵がここで発揮されます。

引数なしで実行

gh workflow run ‘Hello GitHub CLI’ # ワークフロー名で指定
または
gh workflow run hello.yml # ファイル名で指定

実行すると、以下のようなメッセージが表示されます。

✓ Running workflow (ID: 123456789) # このIDは後で使います
To see the run: https://github.com///actions/runs/123456789

`workflow_dispatch`トリガーに`inputs`を設定している場合、引数を渡さずに実行すると、デフォルト値が使われます。

引数を渡して実行

`hello.yml`では`name`という入力項目を定義しました。これをCLIから渡してみましょう。`-f`オプションを使います。

gh workflow run ‘Hello GitHub CLI’ -f name=’DevOps Master’

`-f name=’DevOps Master’` の部分が、ワークフローの `inputs.name` に渡されます。
複数の引数を渡す場合は、`-f key1=value1 -f key2=value2` のように続けて指定します。

4.3. ワークフローの実行状況確認 (runs): `gh run list`

ワークフローを実行したら、その実行状況を確認したいですよね。ブラウザを開くことなく、CLIから確認できます。

gh run list

実行例:

STATUS EVENT BRANCH WORKFLOW TITLE ELAPSED AGE
✓ Success workflow_dispatch main Hello GitHub CLI Hello GitHub CLI (DevOps Master) 16s 2m
✓ Success push main Hello GitHub CLI Update hello.yml 15s 10m
X Failure workflow_dispatch main Deploy to Production Deploy to Production (main) 2m3s 1h

`STATUS`: 実行結果（Success, Failure, In Progressなど）
`EVENT`: トリガーイベント（push, workflow_dispatchなど）
`BRANCH`: 実行されたブランチ
`WORKFLOW`: ワークフローの名前
`TITLE`: 実行タイトル（通常はコミットメッセージやワークフロー名）

最新の実行結果が一番上に表示されます。これを見れば、どのワークフローが成功して、どれが失敗しているか一目瞭然ですね。

特定のワークフローの実行だけを見たい場合は、`–workflow`オプションを使います。

gh run list –workflow ‘Hello GitHub CLI’

4.4. 特定の実行の詳細表示: `gh run view`

`gh run list`で概要は分かりましたが、失敗したときに「なぜ失敗したのか？」を知るには、もっと詳細な情報が必要です。`gh run view`を使えば、特定の実行の詳細を確認できます。

先ほど `gh workflow run` を実行した際に表示された `ID` (例: `123456789`) を使います。

gh run view 123456789

IDが分からない場合は、`gh run list`で表示されるリストから目的の実行を探し、その行の最初のカラム（ID）を使用します。最新の実行を見たいだけなら、IDを指定せずに実行することも可能です。

gh run view –repo / # 最新の実行の詳細を表示 (カレントディレクトリ外から実行する場合)

このコマンドを実行すると、ワークフローの各ジョブのステータス、実行時間、さらに各ステップの詳細なログまで、ターミナル上で確認できるようになります。まるでブラウザのActionsタブを見ているかのような情報量です。

4.5. 実行ログの取得: `gh run view –log` または `gh run download`

`gh run view`で表示されるログは非常に便利ですが、より詳細なログを分析したい、あるいはファイルとして保存したい場合があります。

ターミナルに全ログを表示する: `gh run view –log`

gh run view 123456789 –log

これにより、指定した実行の全ログがターミナルに表示されます。失敗したジョブのログだけを見たい場合は、ジョブ名を指定することも可能です。

gh run view 123456789 –log –job greet # ‘greet’ジョブのログだけを表示

ログファイルをダウンロードする: `gh run download`

すべてのログをまとめてダウンロードしたい場合は、`gh run download`が便利です。

gh run download 123456789

これにより、カレントディレクトリに `123456789_logs.zip` のようなファイルがダウンロードされます。解凍すると、各ジョブのログファイルがテキスト形式で格納されています。

スクリプトからログを解析する際などに非常に役立ちます。

—

5. 実践！CLI自動化の第一歩を踏み出そう

ここまでで、`gh` CLIを使ったGitHub Actionsの基本的な操作をマスターしました。これらを組み合わせることで、いよいよ自動化の扉が開きます。

ここでは、簡単なシェルスクリプトの例として、「特定のワークフローを実行し、その結果を待って、成功/失敗を判定し、ログを表示する」という一連の処理を自動化してみましょう。

`run-and-check-workflow.sh` というファイルを作成してください。

!/bin/bash

run-and-check-workflow.sh

— 設定 —
REPO=”/” # あなたのリポジトリ名に置き換えてください
WORKFLOW_NAME=”Hello GitHub CLI” # 実行したいワークフロー名
INPUT_NAME=”CLI自動化テスト” # ワークフローに渡す名前
WAIT_SECONDS=10 # 実行状況を確認する間隔（秒）
MAX_RETRIES=12 # 最大リトライ回数 (12回 10秒 = 120秒 = 2分まで待つ)

echo “— ワークフロー実行開始 —”
echo “リポジトリ: ${REPO}”
echo “ワークフロー: ${WORKFLOW_NAME}”
echo “入力名: ${INPUT_NAME}”

1. ワークフローを実行し、そのRun IDを取得
-R: リポジトリ指定
-f: ワークフローに引数を渡す
–json id: 実行結果をJSONで取得し、その中の`id`フィールドだけを抽出
RUN_ID=$(gh workflow run “${WORKFLOW_NAME}” -R “${REPO}” -f name=”${INPUT_NAME}” –json id -q)

if [ -z “$RUN_ID” ]; then
echo “エラー: ワークフローの実行に失敗しました。RUN_IDが取得できませんでした。”
exit 1
fi

echo “ワークフロー実行を開始しました。Run ID: ${RUN_ID}”
echo “詳細URL: https://github.com/${REPO}/actions/runs/${RUN_ID}”

2. ワークフローの完了を待機し、結果を確認
echo “— ワークフロー完了待機中 —”
for i in $(seq 1 $MAX_RETRIES); do
# gh run view コマンドで実行ステータスを取得
# –json status: 実行結果をJSONで取得し、その中の`status`フィールドだけを抽出
# -q: クワイエットモード（JSON以外の出力を抑制）
STATUS=$(gh run view “${RUN_ID}” -R “${REPO}” –json status -q)

echo “(${i}/${MAX_RETRIES}) 現在のステータス: ${STATUS}”

if [[ “$STATUS” == “completed” ]]; then
# 完了後、conclusion（成功/失敗）を取得
CONCLUSION=$(gh run view “${RUN_ID}” -R “${REPO}” –json conclusion -q)
echo “— ワークフロー実行完了 —”
echo “最終結果: ${CONCLUSION}”

if [[ “$CONCLUSION” == “success” ]]; then
echo “✅ ワークフローは正常に完了しました！”
# 成功時の処理をここに追加 (例: Slack通知など)
exit 0
else
echo “❌ ワークフローは失敗しました。ログを確認してください。”
# 失敗時の処理をここに追加 (例: エラーログの表示、管理者への通知など)
# 失敗したジョブのログを表示する例
echo “— 失敗したワークフローのログ —”
gh run view “${RUN_ID}” -R “${REPO}” –log –exit-status # –exit-statusでエラー時にシェルも終了させる
exit 1
fi
fi

sleep “$WAIT_SECONDS”
done

echo “タイムアウトしました。ワークフローが ${MAX_RETRIES} 回の確認以内に完了しませんでした。”
exit 1

スクリプトの実行方法:

1. 上記のスクリプトを `run-and-check-workflow.sh` として保存します。
2. `REPO` の部分をあなたのGitHubユーザー名/Organization名とリポジトリ名に置き換えてください（例: `my-org/my-awesome-repo`）。
3. 実行権限を付与します: `chmod +x run-and-check-workflow.sh`
4. 実行します: `./run-and-check-workflow.sh`

このスクリプトは、GitHub ActionsのワークフローをCLIから実行し、その完了を待ち、結果に応じて成功・失敗を判定する一連の処理を自動化しています。

`–json`と`-q`オプションを組み合わせることで、コマンドの出力をJSON形式で取得し、`jq`などのツールと組み合わせることでさらに高度な解析が可能です。
`gh run view –log –exit-status` は、ワークフローが失敗した場合にそのログを表示し、さらにスクリプト自体もエラー終了させる（`exit 1`）ことができる便利なオプションです。

このスクリプトを、cronで定期実行したり、別のCI/CDツール（Jenkins, CircleCIなど）から呼び出したりすれば、あなたのCI/CD運用はさらに柔軟で強力なものとなるでしょう。

—

6. さらに深掘りしたいあなたへ（応用へのヒント）

今回ご紹介したのは、`gh` CLIとGitHub Actionsの連携のほんの入り口に過ぎません。ここからさらに高度な自動化を目指すためのヒントをいくつかご紹介します。

定期的なデプロイやレポートの生成:
`cron` と上記のシェルスクリプトを組み合わせれば、「毎日深夜0時に本番環境へデプロイするワークフローを起動し、その結果をチームのSlackチャンネルに通知する」といった定期的な運用を完全に自動化できます。
エラー発生時の自動リトライ/リカバリ:
ワークフローが失敗した場合、`gh run rerun ` コマンドを使って自動的に再実行させるスクリプトを組むことも可能です。
特定の条件（例えば、テスト環境でのみ）で失敗した場合に、自動で開発者へIssueを作成する、といったことも考えられます。
複数のワークフロー連携:
あるワークフローの成功をトリガーに、別のリポジトリのワークフローを起動したい場合など、`gh` CLIを使って連鎖的にワークフローを制御できます。
詳細な情報取得と解析:
`gh` コマンドは多くの情報をJSON形式で出力できます (`–json` オプション)。これと `jq` のようなJSONパーサーを組み合わせれば、ワークフローの実行時間、各ジョブのステップごとの結果、特定の環境変数など、あらゆる情報をスクリプトで取得・解析し、ビジネスロジックに組み込むことが可能です。
GitHub APIとの連携:
`gh` CLIは、内部的にGitHub REST APIやGraphQL APIを呼び出しています。`gh api` コマンドを使えば、`gh` CLIが直接サポートしていないGitHub APIエンドポイントも叩くことができます。これにより、さらに幅広いGitHubの機能を自動化の対象にできます。

これらの応用例は、あなたのアイデア次第で無限に広がります。ぜひ、日々の開発業務で「これ、自動化できないかな？」と感じたときに、`gh` CLIの可能性を思い出してみてください。

—

7. まとめ

今回は、GitHub ActionsをCLIから自在に操るための強力なツール、GitHub CLI (gh) の基礎とその応用への第一歩を解説しました。

`gh auth login` での簡単な認証設定。
`workflow_dispatch` トリガーを使ったCLIからの手動実行。
`gh workflow list` でのワークフロー一覧確認。
`gh workflow run` でのワークフロー手動実行（引数渡しを含む）。
`gh run list` での実行状況一覧確認。
`gh run view` での特定実行の詳細表示。
`gh run view –log` や `gh run download` でのログ取得。
そして、これらを組み合わせた簡単な自動化スクリプトの例。

ブラウザを開く手間を省き、ターミナルから直接GitHub Actionsを制御するこのスキルは、あなたの開発効率を格段に向上させ、日々のCI/CD運用をより堅牢で柔軟なものに変えるでしょう。

さあ、あなたも今日からCLIの力を手に入れて、GitHub Actionsの真のパワーを引き出し、CI/CDの達人への道を歩み始めましょう！きっと、毎日の作業が劇的に楽になりますよ。

1. GitHub CLI (gh) って何？ その役割と魅力

2. GitHub CLI (gh) のインストールと初期設定

2.1. インストール

macOSの場合 (Homebrewが推奨)

Linuxの場合 (Debian/Ubuntu)

Windowsの場合 (wingetが推奨)

2.2. 初期設定（認証）

2.3. ちょっと便利な追加設定（任意だが推奨）

3. GitHub Actionsの基本的なワークフローを用意しよう (HelloWorld)

4. `gh` CLIでGitHub Actionsを操作する基礎の基礎

4.1. ワークフローの一覧表示: `gh workflow list`

4.2. ワークフローの手動実行 (dispatch): `gh workflow run`

引数なしで実行

引数を渡して実行

4.3. ワークフローの実行状況確認 (runs): `gh run list`

4.4. 特定の実行の詳細表示: `gh run view`

4.5. 実行ログの取得: `gh run view –log` または `gh run download`

ターミナルに全ログを表示する: `gh run view –log`

ログファイルをダウンロードする: `gh run download`

5. 実践！CLI自動化の第一歩を踏み出そう

6. さらに深掘りしたいあなたへ（応用へのヒント）

7. まとめ

1. GitHub CLI (gh) って何？その役割と魅力