Skip to content

External workflow triggering

External workflow triggering is a mechanism in GitHub Actions that allows one workflow to initiate the execution of a separate workflow file, or to trigger the same workflow in different operational modes.^[README.md]

This capability enables complex automation pipelines by chaining distinct workflows together, typically using the repository_dispatch event type.^[README.md] Instead of relying on a single monolithic file, actions can be split into separate, modular components that communicate via specific event triggers.^[README.md]

Triggering Mechanism

The primary method for achieving this is through the repository_dispatch event.^[README.md] In this pattern, a "caller" workflow sends a dispatch event with a specific event type (e.g., run-ping), which acts as a signal for the "receiver" workflow to begin its execution.^[README.md]

Implementation Patterns

There are two common architectural patterns for implementing external triggers:

Multiple Workflows

In this pattern, discrete workflow files are created to handle specific tasks, triggering one another in a sequence.

  • Ping-Pong-Done Chain: A standard example involves three workflows linked sequentially^[README.md]:
    • The Ping workflow listens for the run-ping event type and, upon execution, triggers the Pong workflow.
    • The Pong workflow listens for the run-pong event type and triggers the Done workflow.
    • The Done workflow listens for the run-done event type and outputs a completion status^[README.md].

Single Workflow (Running Modes)

Alternatively, a single workflow file can be designed to handle multiple modes of operation based on the input received.^[README.md] Instead of triggering different files, the caller invokes the same workflow but passes a specific command or parameter in the body of the dispatch event to dictate behavior^[README.md].

  • Dynamic Modes: The workflow listens for a defined set of events (e.g., run-ping-allinone, run-pong-allinone, run-done-allinone) or derives the mode from a payload command^[README.md].
  • Execution Flow:
    • Ping Mode: Triggers the workflow and sets the subsequent running mode to "Pong".
    • Pong Mode: Triggers the workflow and sets the subsequent running mode to "Done".
    • Done Mode: Outputs a completion status^[README.md].

Sources

^[README.md]