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は、リポジトリにカスタムイベントを送信し、そのイベントタイプを待ち受けているワークフローがすべて実行されます。
誰が実行できますか?
リポジトリへの書き込み権限を持つユーザー、または適切な権限を持つトークンを使用する主体です。
関連記事
- Invalid Workflow File: YAML構文エラーの修正方法GitHub Actionsで"Invalid workflow file"と"You have an error in your yaml syntax"を解決する方法:インデント、予期しない値、不正な式をactionlintで確認します。
- GitHub Appによるワークフローの更新を拒否される:修正方法「refusing to allow a GitHub App to create or update workflow without workflows permission」の修正方法:ワークフローへの書き込み権限を持つPATまたはAppトークンを使用してください。
- GitHub Actionsの再利用可能なワークフローとは再利用可能なワークフローとは、他のワークフローが入力とシークレットを渡して呼び出せるGitHub Actionsのワークフローです。workflow_callの構文と、よくある誤りを学びましょう。
- CI分とは? GitHub Actionsの料金の仕組みCI分とは、パイプラインが使用する課金対象のコンピュート時間です。GitHub Actionsでの分の数え方、切り上げと乗数、そして使用量を減らす方法を説明します。