Manual Trigger with workflow_dispatch

Manual Workflows with workflow_dispatch

The workflow_dispatch trigger lets you run workflows manually from the GitHub UI, API, or CLI. You can define custom inputs that appear as form fields, making it perfect for one-off tasks like deployments to specific environments or data migrations.

Workflow YAML

name: Manual Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version tag to deploy'
        required: true
        type: string
        default: 'latest'
      dry-run:
        description: 'Run in dry-run mode'
        required: false
        type: boolean
        default: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.version != 'latest' && inputs.version || '' }}

      - name: Deploy
        if: ${{ !inputs.dry-run }}
        run: |
          echo "Deploying version ${{ inputs.version }} to ${{ inputs.environment }}"
          # actual deploy commands here

      - name: Dry run
        if: ${{ inputs.dry-run }}
        run: |
          echo "[DRY RUN] Would deploy ${{ inputs.version }} to ${{ inputs.environment }}"

Input Types

Type	Description	UI Element
string	Free-form text input	Text field
boolean	True/false toggle	Checkbox
choice	Select from predefined options	Dropdown
environment	Select a GitHub Environment	Environment picker

How to Trigger

1. GitHub UI: Go to Actions tab > select workflow > click "Run workflow"
2. GitHub CLI: gh workflow run deploy.yml -f environment=staging -f version=v1.2.3
3. API: POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches

Using Inputs in Steps

Access inputs with ${{ inputs.name }}. Inputs are always strings when accessed this way; use ${{ inputs.dry-run == true }} for boolean comparison.

Combining with Other Triggers

A workflow can have both workflow_dispatch and other triggers (push, schedule). When triggered manually, the inputs are populated; when triggered automatically, inputs use their default values.