GitHub Dispatches: How They Work, When to Use Them, and Practical Patterns

Executive Summary

GitHub “dispatches” are explicit triggers you can send to start GitHub Actions workflows on demand. There are two primary mechanisms: repository_dispatch, a custom, API-driven event to kick off workflows, often from external systems, and workflow_dispatch, a manual or API-driven event for a specific workflow, typically for human-in-the-loop runs. Both require the workflow file to exist on the default branch to be eligible to run.

Comparison Summary Table

Repository Dispatch Deep Dive

The repository_dispatch event is a custom, API-driven trigger that allows you to start a GitHub Actions workflow on demand. It functions as a webhook event that you can trigger by sending a POST request to a specific GitHub API endpoint for a repository. Its primary use case is to initiate workflows based on activities that occur outside of GitHub, such as from external CI/CD orchestrators, release management tools, cron services, or even other repositories. When a repository_dispatch event is created, you must specify a custom event_type to describe the activity. This allows workflows to filter and respond only to specific types of dispatches. Any additional data can be sent in an optional client_payload object, which then becomes available to the triggered workflow within the github.event context. For a workflow to be triggered by this event, the corresponding workflow file must exist on the repository’s default branch.

Repository Dispatch Configuration

To configure a GitHub Actions workflow to respond to a repository_dispatch event, you must specify the event in the on section of your workflow’s YAML file. The basic configuration is on: repository_dispatch. To make the workflow more specific and prevent it from running for every dispatch event sent to the repository, you can use the types keyword. The types keyword allows you to provide a list of event_type strings that this particular workflow should be triggered by. If the event_type sent in the API request matches one of the values in the types list, the workflow will run. The workflow file containing this configuration must be present on the repository’s default branch to be active.

Here is an example YAML snippet for a workflow that listens for a repository_dispatch event with the event_type of promote:

name: On Repository Dispatch
on:
  repository_dispatch:
    types: [promote]
jobs:
  handle:
    runs-on: ubuntu-latest
    steps:
      - name: Show payload
        run: |
          echo "App: ${{ github.event.client_payload.app }}"
          echo "Env: ${{ github.event.client_payload.env }}"

Workflow Dispatch Deep Dive

The workflow_dispatch event in GitHub Actions is a powerful trigger that allows for the manual or programmatic execution of a specific workflow. Unlike other events that are tied to repository activities like pushes or pull requests, workflow_dispatch is designed for on-demand runs. This makes it ideal for scenarios requiring human intervention, such as deploying to production, running a resource-intensive analysis, or executing a parameterized build. It can be triggered through various methods, including the GitHub user interface, the GitHub CLI, and the REST API. A key feature of this event is its ability to accept custom inputs, which can be defined with specific data types (like string, boolean, or choice), descriptions, and default values. These inputs are then made available to the workflow, enabling flexible and dynamic job execution. To be eligible for a workflow_dispatch trigger, the workflow file containing the configuration must exist on the repository’s default branch.

Workflow Dispatch Configuration

To enable a workflow to be run manually, you must configure it with the workflow_dispatch event trigger in the workflow’s YAML file. This is done by adding on: workflow_dispatch. You can optionally define a map of inputs that will be presented to the user when the workflow is triggered. Each input can have a description, a type (which can be string, number, boolean, choice, or environment), a default value, and a required status. These inputs are then accessible within the workflow’s jobs via the inputs context. The workflow file must be on the default branch for the trigger to be active.

Here is an example YAML configuration:

name: Manual Release
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        type: choice
        options:
          - dev
          - staging
          - prod
        required: true
      dryRun:
        description: 'Do a dry run?'
        type: boolean
        default: true
      version:
        description: 'The version to release'
        type: string
        required: false

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: 'Display Inputs'
        run: |
          echo "Env: ${{ inputs.environment }}"
          echo "Dry run: ${{ inputs.dryRun }}"
          echo "Version: ${{ inputs.version }}"

Cross Repository And Advanced Scenarios

Triggering a workflow in a different repository is an advanced use case that cannot be accomplished using the default GITHUB_TOKEN. The GITHUB_TOKEN’s permissions are strictly scoped to the repository in which the workflow is currently executing. To send a repository_dispatch event to a different (‘remote’) repository, a token with the necessary cross-repository permissions is required. The standard practice is to create a Personal Access Token (PAT)—either a classic PAT with the repo scope or a more secure, fine-grained PAT with Contents: write permissions on the target repository. This PAT is then stored as a secret in the source repository and used to authenticate the API call that creates the dispatch event in the target repository.

Bottom Line Summary

Use repository_dispatch for custom, external, or cross-repo triggers that utilize a structured payload, ensuring minimal required token scopes are used. Opt for workflow_dispatch when you need manual or programmatic runs of a specific workflow with typed inputs, accessible via the UI, CLI, or API. For both, it is crucial to ensure the workflow file resides on the default branch, select the appropriate token and scopes, and design inputs and filters to maintain safe and predictable workflow executions.