How to Use workflow_dispatch to Trigger GitHub Actions Manually

In this tutorial, you'll learn about How to Use workflow_dispatch to Trigger GitHub Actions Manually. We cover key concepts, practical examples, and best practices.

The Problem

Your GitHub Actions workflow currently runs only on push or pull_request, but you frequently need to trigger it on demand — for a one-off database migration, a manual staging deployment, or running tests against a feature branch without pushing a dummy commit. Without workflow_dispatch, you are forced to push empty commits or merge PRs just to trigger a build.

Quick Fix

1. Add workflow_dispatch with input parameters

Create or modify .github/workflows/deploy.yml:

name: Deploy
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      branch:
        description: 'Branch to deploy'
        required: true
        default: 'main'
      dry_run:
        description: 'Dry run (no actual deploy)'
        type: boolean
        default: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.branch }}

      - name: Deploy to ${{ github.event.inputs.environment }}
        run: |
          echo "Deploying branch $BRANCH to $ENV"
          echo "Dry run: $DRY_RUN"
          if [ "$DRY_RUN" = "false" ]; then
            ./deploy.sh "$ENV"
          fi
        env:
          BRANCH: ${{ github.event.inputs.branch }}
          ENV: ${{ github.event.inputs.environment }}
          DRY_RUN: ${{ github.event.inputs.dry_run }}

2. Trigger from the GitHub web UI

Navigate to your repository:

Actions → Select "Deploy" workflow → "Run workflow" dropdown
→ Select branch → Fill in environment and branch → "Run workflow"

The workflow appears in the Actions tab immediately.

3. Trigger from the GitHub CLI

gh workflow run deploy.yml \
  --ref main \
  -f environment=staging \
  -f branch=feature/new-thing \
  -f dry_run=true

Expected output:

✓ Created workflow_dispatch event for deploy.yml at main

4. Check the status of the triggered run

gh run list --workflow=deploy.yml --limit 5

Expected output:

STATUS  TITLE        WORKFLOW  BRANCH              ELAPSED  AGE
✓       deploy       Deploy    feature/new-thing    2m14s    30s ago

5. Add a required approval for production dispatches

on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options:
          - staging
          - production

jobs:
  deploy:
    environment: ${{ github.event.inputs.environment }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ github.event.inputs.environment }}"

Set environment protection rules in GitHub Settings → Environments → production → Required reviewers.

6. Use concurrency to prevent simultaneous dispatches

concurrency:
  group: deploy-${{ github.event.inputs.environment }}
  cancel-in-progress: true

This prevents two people from deploying to the same environment at the same time.

7. Add a dry-run mode for safe testing

on:
  workflow_dispatch:
    inputs:
      dry_run:
        description: 'Dry run (no actual deploy)'
        type: boolean
        default: true

Prevention

• Always provide default values and descriptions for every input field to guide the team
• Use type: choice with explicit options to prevent typos in environment names
• Restrict production deployment by using environment protection rules with required reviewers
• Log the trigger user via ${{ github.actor }} in the workflow for an audit trail
• Add a dry_run boolean input as a safety net for destructive operations