Skip to content
compiler.dev
Start free

What Is workflow_dispatch in GitHub Actions?

Last updated

workflow_dispatch is a GitHub Actions trigger that lets you start a workflow by hand, from the Actions tab, the GitHub CLI or the REST API, optionally passing typed inputs.

How it works

Add workflow_dispatch under on: and, if you want parameters, declare inputs. GitHub then shows a "Run workflow" button in the Actions tab for that workflow, with a branch selector and a form for the inputs. Inside the workflow you read values from github.event.inputs or the inputs context.

Input types are string, boolean, choice, number and environment. A choice input needs an options list. You can mark inputs required and give them a default.

The workflow file must exist on the default branch for the button to appear, though you can then run it against another branch.

Example

on:
  workflow_dispatch:
    inputs:
      environment:
        description: Where to deploy
        type: choice
        options: [staging, production]
        default: staging
      dry_run:
        description: Skip the real deploy
        type: boolean
        default: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying to ${{ inputs.environment }} (dry run: ${{ inputs.dry_run }})"

Trigger it from a terminal:

gh workflow run deploy.yml -f environment=staging -f dry_run=false

Typical uses

  • One-click deploys and rollbacks.
  • Re-running data backfills or maintenance scripts.
  • Benchmark or load-test runs on demand.
  • Testing a scheduled job without waiting for the cron time. See cron schedules.

Common mistakes

  • Workflow not on the default branch. The Run workflow button will not show up until the file is merged.
  • Boolean inputs compared as strings. With the older github.event.inputs context, booleans arrive as strings. Prefer the inputs context, which keeps types.
  • Too many inputs. The API limits the number of inputs, and long forms invite mistakes. Use sensible defaults.
  • No protection on production deploys. Anyone with write access can dispatch. Pair with environment protection rules.
  • Parallel dispatches racing. Two manual deploys at once can collide. Use a concurrency group.

workflow_dispatch is also how a reusable workflow is often exercised during development, alongside workflow_call.

Related terms

FAQ

Can workflow_dispatch be combined with other triggers?

Yes. A workflow can list push, pull_request, schedule and workflow_dispatch together. Inputs are only set on manual runs.

What is the difference between workflow_dispatch and repository_dispatch?

workflow_dispatch targets one named workflow. repository_dispatch sends a custom event to the repository and any workflow listening for that event type runs.

Who can trigger it?

People with write access to the repository, or tokens with the right permissions.

Related