Day 56intermediateMar 28, 2026

Trigger Pipelines Manually with workflow_dispatch

workflow_dispatch gives you a 'Run' button in GitHub with custom inputs for on-demand deployments and tasks.

cicdgithub-actionsdeployment

What

The workflow_dispatch trigger lets you run workflows manually from the GitHub UI with custom input parameters. It's perfect for deployments, releases, or one-off maintenance tasks that shouldn't run automatically on every push. You can define typed inputs like dropdowns, booleans, and text fields that appear as a form in the GitHub Actions UI.

Why It Matters

Not everything should be triggered by a git push. Production deployments, database migrations, and cache clears need human judgment on timing. workflow_dispatch gives your team a controlled, auditable way to trigger these operations with configurable parameters — no SSH access or CLI tools required.

Example

# .github/workflows/deploy.yml
name: Manual Deploy
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version tag to deploy (e.g., v1.2.3)'
        required: true
        type: string
      dry-run:
        description: 'Perform a dry run without deploying'
        required: false
        type: boolean
        default: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.version }}
      - name: Deploy
        if: ${{ !inputs.dry-run }}
        run: |
          echo "Deploying ${{ inputs.version }} to ${{ inputs.environment }}"
          # ./scripts/deploy.sh ${{ inputs.environment }}
      - name: Dry run
        if: ${{ inputs.dry-run }}
        run: |
          echo "DRY RUN: Would deploy ${{ inputs.version }} to ${{ inputs.environment }}"

yaml

Common Mistake

Not adding input validation. Anyone with write access can trigger the workflow with any input value. A typo in the version tag or selecting the wrong environment can cause a bad deployment. Use choice types for constrained inputs and add validation steps.

Quick Fix

Use type: choice for environment selection instead of free-text strings, add a validation step that checks if the version tag exists before deploying, and use GitHub environment protection rules for production deployments.