はじめに
業務でGitHub Actionsを利用する機会が増えてきたため、手動実行（workflow_dispatch）を中⼼に最小構成を整理します。
この記事では、たった数行の「Manual Ping」を題材に、UIだけで手動実行できる形を作り、入力の扱い、実行ログの見方、運用に役立つ小さな拡張までを段階的に示します。
この記事でできること
- Run workflow ボタンで手動実行できる最小ワークフローの作成
-
inputsにより実行時に値を受け取り、ワークフロー内で利用 - 実行ログでの確認方法と、つまずきやすい点の整理
- 運用で有効な 実行名の明示／入力チェック／Artifacts保存／並行実行の抑止 などの拡張パターン
1. 概要：GitHub Actions の主な用語
- Workflow：
.github/workflows/*.ymlに書く“台本”。トリガー・ジョブ・ステップの集合。 - Job：ワークフロー内の処理のかたまり（基本は並列）。依存関係は
needsで表現。 - Step：ジョブ内の1手順（シェル実行 or
uses:でアクション呼び出し）。 - Runner：実行環境（例：
ubuntu-latest）。 - Event：実行のトリガーとなるもの。
push/pull_request/schedule/workflow_dispatch（手動）など。
手動実行を使うには、Workflowがデフォルトブランチ上に存在している必要があります。
2. 最小サンプル（Manual Ping）
.github/workflows/manual-ping.yml
name: Manual Ping
on:
workflow_dispatch:
inputs:
msg:
type: string
required: false
description: "any message"
jobs:
ping:
runs-on: ubuntu-latest
steps:
- run: |
echo "Hello from Actions!"
echo "msg='${{ inputs.msg }}'"
実行手順（UI）
-
リポジトリに上記ファイルを追加し、デフォルトブランチ（例：
main）へ push -
GitHub → Actions タブ → 左の一覧から Manual Ping を選択
-
右上 Run workflow → Branch を選び、必要に応じて
msgを入力 → Run workflow
-
実行された Run を開き、ログに
Hello from Actions!とmsg='...'が出力されていることを確認
3. 要点のコード解説
on.workflow_dispatch
- 手動実行を有効化（UIに Run workflow ボタンが表示）
inputs.msg
- 実行ダイアログで受け取る文字列。ワークフロー内では
inputs.msgで参照
runs-on: ubuntu-latest
- GitHubホストのLinuxランナーで実行。
steps.run:
- シェルスクリプトとして
echoを実行。結果は実行ログに出力。
4. 拡張パターン
4.1 実行名（run-name）の明示
- 誰が何を実行したかを履歴で見分けやすくします。
run-name: "Ping by @${{ github.actor }} (msg='${{ inputs.msg || '—' }}')"
4.2 権限の最小化（permissions）
- 不要な書き込み権限を避けるのが基本方針です。
permissions:
contents: read
4.3 入力値の検査（バリデーション）
- 要件に合わせて警告または失敗にできます。
- name: Validate input
shell: bash
run: |
set -Eeuo pipefail
msg="${{ inputs.msg || '' }}"
char_count=$(printf '%s' "$msg" | wc -m | tr -d ' ')
if [ "$char_count" -gt 200 ]; then
echo "::error::msg is too long (${char_count} > 200 chars)."
exit 1
fi
4.4 成果物（Artifacts）の保存と保持期間
- 実行結果をファイルとして残し、保持期間を設定します。
- name: Save result
run: |
echo "time=$(date -u +%FT%TZ)" > ping.txt
echo "actor=${{ github.actor }}" >> ping.txt
echo "msg=${{ inputs.msg }}" >> ping.txt
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: ping-result
path: ping.txt
retention-days: 14
4.5 並行実行の抑止（多重起動ガード）
- ボタン連打や重複起動を防ぎます。
concurrency:
group: ${{ github.workflow }} # ワークフロー名単位で排他
cancel-in-progress: true # 先行Runを自動キャンセル
4.6 実行サマリ（監査性の向上）
- Run 画面の「Summary」に要約を残します（レビューが楽になります）
- name: Write summary
run: |
{
echo "## Manual Ping Summary"
echo "- Actor: @${{ github.actor }}"
echo "- Message: \`${{ inputs.msg || '' }}\`"
echo "- Commit: \`${{ github.sha }}\`"
} >> "$GITHUB_STEP_SUMMARY"
4.7 ブランチ運用の基礎ガード
- 検証は
feature/*ブランチ、本番相当はmainブランチのみに限定したい等、最小限の条件分岐を置けます。
- name: Guard branch
if: ${{ !startsWith(github.ref, 'refs/heads/') }}
run: echo "::warning::Not a branch run."
※より厳密には Environments 側の「Deployment branches」や、保護ルールで統制する必要があります
5. 実務向けミニ完成版
- 前述までに作成した最小構成を保ちつつ、権限最小化／排他／入力検査／成果物／サマリを含めた実務寄りの雛形は以下の通りです。
name: Manual Ping
run-name: "Ping by @${{ github.actor }} (msg='${{ inputs.msg || '—' }}')"
on:
workflow_dispatch:
inputs:
msg:
type: string
required: false
description: "any message"
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}
cancel-in-progress: true
jobs:
ping:
runs-on: ubuntu-latest
steps:
- name: Validate input
shell: bash
run: |
set -Eeuo pipefail
msg="${{ inputs.msg || '' }}"
char_count=$(printf '%s' "$msg" | wc -m | tr -d ' ')
if [ "$char_count" -gt 200 ]; then
echo "::error::msg is too long (${char_count} > 200 chars)."
exit 1
fi
- name: Print
run: |
echo "Hello from Actions!"
echo "msg='${{ inputs.msg }}'"
- name: Save result
run: |
echo "time=$(date -u +%FT%TZ)" > ping.txt
echo "actor=${{ github.actor }}" >> ping.txt
echo "msg=${{ inputs.msg }}" >> ping.txt
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: ping-result
path: ping.txt
retention-days: 14
- name: Write summary
run: |
{
echo "## Manual Ping Summary"
echo "- Actor: @${{ github.actor }}"
echo "- Message: \`${{ inputs.msg || '' }}\`"
echo "- Commit: \`${{ github.sha }}\`"
} >> "$GITHUB_STEP_SUMMARY"
6. 実行後のUI：確認ポイント
-
Run overview：手動トリガー（workflow_dispatch）で起動し、run-nameに起動者と入力が表示されていること -
Artifacts：成果物ping-resultからping.txtをダウンロード可能であること。 -
Summary：$GITHUB_STEP_SUMMARYの要約（Actor/Message/Commit）が表示されていること。
-
Jobs/Steps：各ステップのログは展開式であること。
-
Concurrency: 後続Runに置き換えられ、先行Runはキュー状態（待ち）になること
7.さらに一歩：承認ゲートを入れる最小例（任意）
- GitHubの
Environmentsを使うと、手動実行のあとに人の承認を必須化できます。 -
Settings→Environmentsでdev/stg/prdを作成し、Required reviewersや自己承認禁止を設定。あとはenvironmentをジョブへ指定するだけで可能です。
on:
workflow_dispatch:
inputs:
env: { type: choice, required: true, options: [dev, stg, prd], description: "target" }
jobs:
gated:
runs-on: ubuntu-latest
environment:
name: ${{ inputs.env }} # ← Environments の保護ルールが適用
steps:
- run: echo "Approved run for ${{
inputs.env }} by @${{ github.actor }}"
これで、実行→承認待ち→レビュー承認後に続行、という流れが作れます。
8. よくあるつまずき（チェックリスト）
Runボタンが表示されない
- パスが
.github/workflows/か、on: workflow_dispatch:が記載されているか、Actionsが有効か - ワークフローがデフォルトブランチ上に存在するか
意図と異なるYAMLが走る
- 実行時に選んだ Branch 上のYAMLが使われるため、正しい Branch を選択しているか
入力が反映されない
- 参照は
inputs.<name>だが、正しい記載になっているか
多重実行で衝突
-
concurrencyを設定して排他（必要に応じて環境名や ref をキーに含める）
おわりに
-
workflow_dispatchで“人が押す”ワークフローを用意すると、安全で意図が明確な運用を構築できます。 - 実務では、権限の最小化／排他（concurrency）／入力検査／成果物（Artifacts）／実行サマリを重ねるだけでも、監査性と安全性は大きく向上します。
- まだまだ学習中なので、
push・pull_request・schedule・workflow_callなどの他トリガーも順に試し、運用の型を広げていきたいです。