Implementing Parameterized Manual Triggers with GitHub Actions workflow_dispatch

The Problem: Static Workflows vs. Dynamic Execution

Standard CI/CD pipelines often rely on triggers like push or pull_request, which execute the same logic every time. However, many engineering tasks—such as deploying a specific hotfix to a staging environment, triggering a manual database migration, or running a heavy integration test suite against a specific version—require human intervention and custom parameters.

The workflow_dispatch event solves this by allowing you to define a manual trigger with a custom input form. This removes the need to commit "dummy" changes to a branch just to trigger a run or hard-code environment variables that change frequently.

Configuring the workflow_dispatch Trigger

To enable manual triggers, you must define the on: workflow_dispatch key in your YAML file. You can specify inputs to create a UI form in GitHub that prompts the user for data before the workflow starts.

Below is a configuration for a deployment workflow that allows a user to select the target environment and a specific version tag.

name: Manual Deployment

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target Environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version Tag to Deploy'
        required: true
        type: string
      run_migrations:
        description: 'Run DB Migrations?'
        required: false
        type: boolean
        default: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Deploy Application
        run: |
          echo "Deploying version ${{ github.event.inputs.version }} to ${{ github.event.inputs.environment }}"
          # Example deployment command
          # ./deploy.sh --env ${{ github.event.inputs.environment }} --tag ${{ github.event.inputs.version }}

      - name: Handle Migrations
        if: ${{ github.event.inputs.run_migrations == 'true' }}
        run: echo "Running database migrations..."

How to Access Inputs

Inputs are stored in the github.event.inputs context. In the example above, ${{ github.event.inputs.version }} retrieves the string provided by the user. Note that these values are available as context variables throughout the entire workflow run.

Critical Limitations and Implementation Risks

The Default Branch Requirement

A common point of failure is the "missing button" problem. For a workflow to appear in the GitHub Actions UI under the "Run workflow" dropdown, the YAML file must exist on the repository's default branch (usually main or master). If you create a new workflow file on a feature branch, it will not be visible in the UI until it is merged into the default branch, even if the workflow_dispatch trigger is correctly defined.

The Boolean String Trap

Although the type: boolean input provides a checkbox in the UI, GitHub Actions passes all input values to the runner as strings. This means a boolean true is passed as the string 'true'.

When using these in a shell script or an if conditional, you must compare them as strings. For example, using if: ${{ github.event.inputs.run_migrations }} may evaluate unexpectedly; instead, use if: ${{ github.event.inputs.run_migrations == 'true' }}.

Permission Requirements

To trigger a workflow_dispatch event via the UI or the REST API, the user must have write access to the repository. Users with read access cannot manually trigger workflows.

Verification and Testing

To verify your implementation, follow these steps:

1. Commit the workflow file to your default branch.
2. Navigate to the Actions tab in your GitHub repository.
3. Select the workflow name from the left-hand sidebar.
4. Look for the banner: "This workflow has a workflow_dispatch event trigger."
5. Click Run workflow, fill in the parameters, and execute.
6. Check the job logs to ensure the echo commands printed the expected input values.

Comparison: workflow_dispatch vs. repository_dispatch