GitHub Actions Tutorial — Workflow Dispatch

2 minute read

Workflow Dispatch — Manual Triggers

Sometimes you need to run a workflow on demand — not on every push, but when you choose. The workflow_dispatch trigger lets you start a workflow manually from the GitHub UI or the API, with optional input parameters.

Basic Manual Trigger

Add workflow_dispatch to your workflow’s on: section:


name: Manual Deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: echo "Deploying on manual trigger!"

After pushing this file, go to Actions → Manual Deploy → Run workflow. You’ll see a “Run workflow” button.

Adding Input Parameters

You can define inputs that appear as form fields when you trigger the workflow:


name: Deploy to Environment

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version to deploy'
        required: true
        type: string
      dry-run:
        description: 'Perform a dry run?'
        required: false
        default: false
        type: boolean

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Show inputs
        run: |
          echo "Environment: ${{ github.event.inputs.environment }}"
          echo "Version: ${{ github.event.inputs.version }}"
          echo "Dry run: ${{ github.event.inputs.dry-run }}"

      - name: Deploy
        if: github.event.inputs.dry-run == 'false'
        run: echo "Deploying version ${{ github.event.inputs.version }} to ${{ github.event.inputs.environment }}"

Input Types

Type UI Element Example
string Text input Version number, tag name
boolean Checkbox Enable/disable a feature
choice Dropdown Environment selection
environment Environment selector Uses GitHub Environments

Triggering via API

You can also trigger workflow_dispatch programmatically:


curl -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token YOUR_PAT" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches \
  -d '{"ref":"main","inputs":{"environment":"production","version":"2.1.0","dry-run":"false"}}'

This is useful for integrating GitHub Actions with external tools (Slack bots, dashboards, other CI systems).

Combining with Other Triggers

workflow_dispatch works alongside other triggers:


on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

This workflow runs automatically on push to main and can be triggered manually with environment selection.

Common Mistakes

Mistake Fix
“Run workflow” button doesn’t appear The workflow file with workflow_dispatch must exist on the default branch (e.g., main)
Inputs are empty strings Access via ${{ github.event.inputs.name }}, not ${{ inputs.name }} (the latter only works inside reusable workflows)
Boolean input is string “true”/”false” Compare with == 'true' not == true in if: conditions

Quick Reference

Concept Syntax
Basic trigger on: workflow_dispatch:
String input type: string
Boolean input type: boolean
Choice input type: choice + options:
Access input ${{ github.event.inputs.<name> }}
API trigger POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches

← Previous: Workflow Structure

Next: Viewing Results →

Updated:

You may also enjoy