コンテンツへスキップ

GitHub Actionsのworkflow_dispatchとは

最終更新

workflow_dispatchは、GitHub Actionsのトリガーの一つで、Actionsタブ、GitHub CLI、REST APIからワークフローを手動で開始できます。必要に応じて、型付きの入力値を渡すこともできます。

仕組み

on:の下にworkflow_dispatchを追加し、パラメータが必要な場合はinputsを宣言します。すると、GitHubはそのワークフローのActionsタブに「Run workflow」ボタンを表示し、ブランチの選択欄と入力フォームを表示します。ワークフロー内では、github.event.inputsまたはinputsコンテキストから値を読み取ります。

入力の型にはstring、boolean、choice、number、environmentがあります。choice型の入力にはoptionsのリストが必要です。入力にはrequiredを指定して必須にしたり、defaultで初期値を設定したりできます。

ボタンを表示するには、ワークフローファイルがデフォルトブランチに存在している必要があります。ただし、その後は別のブランチを対象にして実行することもできます。

例

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Where to deploy
        type: choice
        options: [staging, production]
        default: staging
      dry_run:
        description: Skip the real deploy
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying to ${{ inputs.environment }} (dry run: ${{ inputs.dry_run }})"

ターミナルから実行する場合は、次のように入力します。

gh workflow run deploy.yml -f environment=staging -f dry_run=false

主な用途

  • ワンクリックでのデプロイとロールバック。
  • データのバックフィルやメンテナンススクリプトの再実行。
  • 必要に応じたベンチマークや負荷テストの実行。
  • cronの時刻を待たずに、スケジュールされたジョブをテストする。詳しくはcronスケジュールをご覧ください。

よくある間違い

  • ワークフローがデフォルトブランチにない。ファイルがマージされるまで、Run workflowボタンは表示されません。
  • boolean入力を文字列として比較している。従来のgithub.event.inputsコンテキストでは、真偽値は文字列として渡されます。型が保持されるinputsコンテキストの利用を推奨します。
  • 入力が多すぎる。APIには入力数の上限があり、長いフォームは入力ミスの原因になります。適切なデフォルト値を設定してください。
  • 本番デプロイに保護がない。書き込み権限を持つ人なら誰でも実行できます。環境の保護ルールと組み合わせてください。
  • 並列実行が競合する。手動デプロイを同時に2つ実行すると衝突することがあります。同時実行グループを使用してください。

workflow_dispatchは、開発中に再利用可能なワークフローを動作させる際にもよく使われます。workflow_callと合わせて利用されることもあります。

よくある質問

workflow_dispatchは他のトリガーと組み合わせられますか?

はい。1つのワークフローで、push、pull_request、schedule、workflow_dispatchをまとめて指定できます。入力値は手動実行の場合にのみ設定されます。

workflow_dispatchとrepository_dispatchの違いは何ですか?

workflow_dispatchは、名前を指定した1つのワークフローを対象とします。repository_dispatchは、リポジトリにカスタムイベントを送信し、そのイベントタイプを待ち受けているワークフローがすべて実行されます。

誰が実行できますか?

リポジトリへの書き込み権限を持つユーザー、または適切な権限を持つトークンを使用する主体です。