Manual Workflow Triggers with workflow_dispatch
What you'll learn: How to enable on-demand workflow execution with custom inputs using GitHub Actions' workflow_dispatch event.
The Concept
Not every workflow should run automatically on every push or pull request. Sometimes you need to trigger a deployment, run a maintenance task, or execute a diagnostic workflow only when you explicitly decide to. The workflow_dispatch event is GitHub Actions' mechanism for manual workflow execution—it adds a "Run workflow" button directly in the GitHub UI and optionally allows you to pass parameters to customize each run.
Think of it like the difference between an automatic sprinkler system (scheduled or event-triggered workflows) and a garden hose you control manually (workflow_dispatch). You decide when to turn it on and how much water to use.
Defining Manual Triggers
To enable manual execution, add workflow_dispatch to your workflow's on section:
on:
workflow_dispatch:
inputs:
environment:
description: 'Target environment'
required: true
default: 'staging'
type: choice
options:
- staging
- production
version:
description: 'Version to deploy'
required: true
You can then access these inputs in your workflow steps using ${{ github.event.inputs.environment }} or ${{ github.event.inputs.version }}.
When to Use It
Manual triggers are perfect for deployment workflows, data migrations, emergency rollbacks, or any operation requiring human judgment before execution. They combine the power of automation with the control of manual decision-making.
Key Takeaway: workflow_dispatch transforms workflows into on-demand tools with customizable inputs, giving you control over when and how workflows execute while maintaining the benefits of automation.