GitHub Actions の workflow_dispatch イベントとは？

workflow_dispatch イベントは、Actions タブまたは API から手動で workflow を開始でき、オプションで input を渡せます。

すべての workflow が自動的に実行されるべきではありません。workflow_dispatch トリガーは「Run workflow」ボタンを追加し、人がオンデマンドでジョブを起動できるようにします。これは deploy や一度きりのメンテナンスタスクに理想的です。

それは何か

GitHub UI に手動実行ボタンと REST API エンドポイントを公開するトリガーです。オペレーターが実行時に入力する型付き input を宣言できます。

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        type: choice
        options: [staging, production]

どう動くか

workflow_dispatch を持つ workflow がデフォルトブランチにあると、GitHub は「Run workflow」コントロールを表示します。選択された input は workflow 内で ${{ inputs.<name> }} として利用できます。

一般的な用途

• 選択した environment への deploy をトリガーする。
• アドホックなメンテナンスやマイグレーションのジョブを実行する。
• 異なるパラメーターでパイプラインを再実行する。

なぜ重要か

手動 dispatch は、使い捨てのコードをコミットせずに、制御されたオンデマンドの自動化を提供します。型付き input はそれらの実行を安全で自己文書化されたものにします。

関連する概念

これは多くのトリガーの 1 つで、保護されたリリースのために environment や deployment と組み合わせて使われることがよくあります。

重要なポイント

• workflow_dispatch は手動実行を有効にします。
• ${{ inputs.x }} で読む型付き input を宣言できます。
• 表示されるには workflow がデフォルトブランチにある必要があります。

関連ガイド