In the landscape of modern DevOps, the ability to decouple build, test, and deployment stages while maintaining seamless communication between them is critical. GitHub Actions provides powerful mechanisms for this orchestration, primarily through two distinct but related concepts: the repository_dispatch event and the workflow_dispatch trigger. While workflow_dispatch allows users to manually trigger workflows with custom inputs, repository_dispatch enables one workflow to programmatically trigger another, either within the same repository or across different repositories. Understanding the nuances, security requirements, and implementation details of these dispatch mechanisms is essential for building robust, maintainable CI/CD pipelines.
The Repository Dispatch Event
The repository_dispatch event is a webhook event that can be created by a GitHub Action to trigger a workflow. This mechanism is particularly useful for cross-repository interactions, such as triggering a deployment in a production repository after a successful build in a development repository, or updating documentation in a separate docs repository after a code merge. The peter-evans/repository-dispatch action is a widely adopted tool for creating these events.
To utilize this action, a caller workflow file defines a job that runs the dispatch action. This workflow must specify the necessary permissions, particularly contents: write, to ensure the action can create events. The action is invoked using the uses directive, pointing to a specific version, such as peter-evans/repository-dispatch@v4. The event-type input is required and serves as a unique identifier for the webhook event. This event type must match the filter defined in the callee workflow file.
yaml
jobs:
Dispatch:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Repository Dispatch
uses: peter-evans/repository-dispatch@v4
with:
event-type: my-event
On the receiving end, the callee workflow file must be configured to listen for this specific repository_dispatch event. The on block specifies the event type, and the types array filters for the specific event-type defined in the caller. This ensures that only the intended dispatch events trigger the workflow.
yaml
name: MyWorkflow
on:
repository_dispatch:
types: [my-event]
Authentication and Token Management
Security is a paramount consideration when dispatching events, especially when interacting with external repositories. The peter-evans/repository-dispatch action supports two primary authentication methods: the default GITHUB_TOKEN and a Personal Access Token (PAT).
The default GITHUB_TOKEN is automatically generated by GitHub for each workflow run. However, its scope is limited to the repository where the workflow is executing. Therefore, it can only be used to dispatch events within the same repository. Attempting to use the GITHUB_TOKEN to dispatch to a remote repository will fail due to insufficient permissions.
yaml
uses: peter-evans/repository-dispatch@v4
with:
token: ${{ secrets.PAT }}
repository: username/my-repo
event-type: my-event
For cross-repository dispatches, a Personal Access Token (PAT) is required. This token must be stored as a secret in the repository, typically under secrets.PAT. The PAT must have the appropriate scopes to interact with the target repository. For private repositories, the repo scope is necessary. For public repositories, the more limited public_repo scope can be used. GitHub also supports fine-grained personal access tokens, which offer more granular control over permissions and are recommended for enhanced security.
| Parameter | Description | Default |
|---|---|---|
token |
GITHUB_TOKEN or a repo scoped Personal Access Token (PAT). |
GITHUB_TOKEN |
repository |
The full name of the repository to send the dispatch. | github.repository |
event-type |
(required) A custom webhook event name. | |
client-payload |
JSON payload with extra information about the webhook event. | {} |
Passing Data with Client Payloads
One of the most powerful features of repository_dispatch is the ability to pass data between workflows via the client-payload. This parameter accepts a JSON object containing any information that the receiving workflow might need. The receiving workflow can access this data using the github.event.client_payload context.
For example, if the caller workflow sends a JSON payload with a message field, the callee workflow can extract and use this information in its steps. This allows for dynamic behavior, such as passing build artifacts information, version numbers, or specific configuration parameters to the triggered workflow.
yaml
- name: Repository Dispatch
uses: peter-evans/repository-dispatch@v4
with:
event-type: my-event
client-payload: '{"message": "Build completed successfully", "version": "1.0.0"}'
In the callee workflow, this data can be accessed as follows:
yaml
- name: Print payload message
run: echo ${{ github.event.client_payload.message }}
Alternative Dispatch Actions
While peter-evans/repository-dispatch is a popular choice, other actions exist, such as mvasigh/dispatch-action. This action serves a similar purpose but has distinct characteristics and limitations. Notably, the mvasigh/dispatch-action is no longer maintained, and users are advised to consider alternatives. However, understanding its structure can provide insight into the broader ecosystem of dispatch actions.
This action requires a Personal Access Token with the repo scope for private repositories or public_repo for public repositories. It accepts inputs for token, event_type, repo, owner, and message. The message input is optional and must be a JSON string. It also hydrates the client_payload of the repository dispatch event with the original event payload under the event key, allowing the receiving workflow to access the context of the triggering event.
yaml
- name: Dispatch submodule_push event
uses: mvasigh/dispatch-action@main
with:
token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
repo: '@'
event_type: submodule_push
message: |
{
"foo": "bar"
}
The receiving workflow can then access the custom message:
yaml
- name: Print custom message
run: echo ${{ github.event.client_payload.message.foo }}
It is crucial to note that this action is not certified by GitHub and is deprecated. Users should migrate to maintained alternatives like peter-evans/repository-dispatch to ensure reliability and security.
Workflow Dispatch and Manual Inputs
Distinct from repository_dispatch, the workflow_dispatch trigger allows workflows to be manually triggered by users through the GitHub UI. This is useful for on-demand tasks, such as triggering a deployment to a specific environment or running a cleanup job. A key feature of workflow_dispatch is the ability to define custom inputs, which enhance usability by allowing users to specify parameters when triggering the workflow.
GitHub supports up to 10 top-level inputs in a workflow_dispatch trigger. These inputs can have descriptive names and default values, simplifying the user experience. By specifying parameters, teams can create a more intuitive, guided interface for their contributors. This approach is particularly beneficial for complex workflows that require specific configuration options to be set at runtime.
For details on defining these inputs, the Workflow Syntax documentation provides comprehensive guidelines. This feature allows for greater flexibility and control over manual workflows, making them more adaptable to various use cases.
Chaining Workflows with Workflow Dispatch
While repository_dispatch is often used for cross-repository triggers, workflow_dispatch can also be used to chain workflows within the same repository. This pattern is common in CI/CD pipelines, where a CI build workflow might trigger a CD release or deploy workflow upon successful completion. By maintaining separate workflows for CI and CD, teams can enforce clear separation of concerns and improve the maintainability of their pipelines.
GitHub also provides a native way to chain workflows called "reusable workflows." Reusable workflows offer a more structured approach to code reuse and dependency management. However, the workflow_dispatch approach remains valuable for scenarios where manual intervention or specific data passing is required. When using an action to trigger a workflow_dispatch event, the GitHub UI may report the triggered workflow as "manually triggered." This is because the workflow_dispatch event is designed to be triggered manually by a user, and the action simulates this manual trigger.
Recent enhancements to GitHub Actions have introduced the ability to retrieve details of the triggered workflow run, including the run ID and URL. This allows for advanced orchestration, such as polling for the run status and waiting for the triggered workflow to complete before proceeding with subsequent steps. This capability addresses a long-standing need in complex CI/CD pipelines, where synchronization between workflows is essential.
Conclusion
The ability to dispatch events and trigger workflows in GitHub Actions is a cornerstone of effective DevOps automation. Whether using repository_dispatch for cross-repository interactions or workflow_dispatch for manual, parameterized triggers, understanding the underlying mechanics is crucial. Security considerations, such as proper token management and scope limitations, must be rigorously applied to protect repository integrity. As GitHub continues to evolve, with features like reusable workflows and enhanced run status retrieval, the landscape of workflow orchestration becomes increasingly powerful. Teams should carefully evaluate their needs, choosing between legacy actions, maintained alternatives, and native GitHub features to build resilient and efficient CI/CD pipelines.