できない.dev

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

Run workflow ボタンが出ないのは、workflow_dispatch を含むワークフローがデフォルトブランチに無いのが主因。
ほかに on: の構文ミス、ワークフローの無効化、権限不足でも手動実行できなくなる。

公開: 更新:

要約

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

解決策

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 表示の問題と切り離して検証できる。
失敗時は理由(定義が見つからない、権限不足など)がエラーメッセージとして返るので、切り分けに役立つ。

よくある原因

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