github-workflow-dispatch¶

github-workflow-dispatch (often implemented via repository_dispatch) refers to a GitHub Actions capability that enables workflows to be triggered programmatically by external tools or other workflows, rather than by standard events like pushes or pull requests^[devops-ci__github-action__README.md].

Mechanism¶

This functionality relies on specific event types to trigger the target workflow. In the provided examples, workflows listen for custom event types such as run-ping, run-pong, or run-done^[devops-ci__github-action__README.md]. When a dispatch event matching one of these types is received, the corresponding workflow execution begins^[devops-ci__github-action__README.md].

Usage Patterns¶

There are two primary patterns for using dispatch events to manage workflow execution:

Multiple Workflows¶

In this pattern, a chain of workflows is created where one workflow triggers the next^[devops-ci__github-action__README.md]. For example, a "Ping" workflow triggers a "Pong" workflow, which in turn triggers a "Done" workflow^[devops-ci__github-action__README.md]. Each workflow listens for a distinct, specific event type unique to its purpose^[devops-ci__github-action__README.md].

Single Workflow (Running Modes)¶

This pattern consolidates logic into a single workflow that listens for multiple event types (e.g., run-ping-allinone, run-pong-allinone)^[devops-ci__github-action__README.md]. Instead of relying solely on the event type to determine behavior, the workflow accepts a specific parameter (referred to as a "running mode") within the body of the dispatch event^[devops-ci__github-action__README.md]. This allows the same workflow to perform different actions—such as "Ping", "Pong", or "Done"—based on the provided command^[devops-ci__github-action__README.md].

Sources¶

^[devops-ci__github-action__README.md]