GitHub Actions の workflow_dispatch で手動実行できない（Run workflow が出ない）

要約

GitHub Actions の workflow_dispatch を追加したのに Actions タブに「Run workflow」ボタンが表示されず手動実行できない場合、最有力の原因は そのワークフローファイルがデフォルトブランチに存在しない こと。workflow_dispatch トリガは、デフォルトブランチ上のワークフロー定義が認識されて初めて UI に現れる。
作業ブランチに置いただけでは、何度 push してもボタンは出ない。

よくある原因

1. デフォルトブランチに未マージ: workflow_dispatch の定義が feature ブランチにしか無い
2. YAML 構文の誤り: on: 直下ではなく別の階層に書いている、インデントが崩れている
3. 無効化・権限不足: ワークフローが Disabled になっている、または書き込み権限が無いアカウントで見ている
4. ブランチ選択の取り違え: Run workflow のドロップダウンで、ファイルが存在しないブランチを選んでいる

解決策

1. デフォルトブランチへマージする

workflow_dispatch を含むワークフローファイルを、まず main などのデフォルトブランチに入れる。
マージ後は、Run workflow 実行時のブランチ選択で feature ブランチを指定すれば、そのブランチ上の内容で 実行できる。
トリガの仕様は 公式ドキュメントの workflow_dispatch に記載がある。

2. on: の構文を確認する

on:
  workflow_dispatch:
    inputs:
      environment:
        description: "デプロイ先"
        required: true
        default: "staging"

入力が不要なら workflow_dispatch: だけの空定義でよい。on: [push] のようなフロー配列と混在させる場合は、on: をマッピング形式に書き換える必要がある。

3. 無効化と権限を確認する

Actions タブでワークフロー名の横に「This workflow was disabled」と出ていないか確認する。
public リポジトリでは 60 日間活動が無いと scheduled workflow が無効化されるが、手動実行ボタン自体も書き込み権限が無いユーザーには表示されない。

4. CLI から起動して切り分ける

gh workflow run deploy.yml --ref main
gh run list --workflow=deploy.yml

GitHub CLI からの起動は UI 表示の問題と切り離して検証でき、失敗時は理由（定義が見つからない、権限不足など）がエラーメッセージとして返るため切り分けに有効。