How to Leverage the GitHub repository_dispatch Event for Custom Triggers
- Oct 21, 2021
- 4 min read
Updated: Mar 28
Table of Contents:
Overview
GitHub Actions is a powerful automation tool that allows you to automate workflows, such as continuous integration (CI), continuous delivery (CD), and much more. One of the key components of GitHub Actions is the ability to trigger workflows in a variety of ways, including via GitHub events. One such event is the repository_dispatch event, which enables external services or systems to trigger workflows in your repository.
In this blog, we’ll dive into the repository_dispatch event, explain how it works, and provide examples of how to implement it in real-world scenarios.
What is the repository_dispatch Event?
The repository_dispatch event in GitHub Actions is a manual trigger that allows you to initiate a workflow from an external source. This event is particularly useful when you need to trigger workflows in response to events outside GitHub, such as a webhook, a third-party service, or even another repository.
This event can be used to send custom payload data to your repository and initiate a workflow based on that data. You can customize the payload to pass specific information to the workflow, making it flexible for a wide range of use cases.
How to Use the repository_dispatch Event?
To trigger a workflow using the repository_dispatch event, you need to set up the event in two places:
In the GitHub Actions Workflow: Define the repository_dispatch event as the trigger for your workflow.
Send the Triggering Event: Use an external service or tool to send a repository_dispatch event to GitHub.
Triggering a Workflow with repository_dispatch
Here’s an example of a GitHub Actions workflow that’s triggered by the repository_dispatch event.
Step 1: Define a Workflow to Listen for repository_dispatch
In your repository, create a .github/workflows/triggered-workflow.yml file:
name: Triggered Workflow
on: repository_dispatch:
types: "build"
jobs:
run_triggered_action:
runs-on: devops-runner
steps:
- name: Step to checkout code
uses: actions/checkout@v2
- name: Step to run a script
run: |
echo "This workflow was triggered by the repository_dispatch event" echo "Payload data: ${{ github.event.client_payload.version }}"Step 2: Trigger the Event Using the GitHub API
You can trigger this workflow by sending a repository_dispatch event to GitHub using the GitHub REST API. This can be done with a tool like curl or Postman.
Example curl command to trigger the event:
curl -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token <GITHUB_TOKEN>" \
--data '{"event_type": "build", "client_payload": {"version": "1.0.0"}}' \
https://api.github.com/repos/anantacloud/terraform-modules/dispatchesExplanation:
event_type: A custom event name, in this case, "build" is the custom event used to filter which events trigger the workflow.
client_payload: This allows you to pass additional data (e.g., version) to your workflow.
When this API call is executed, the workflow triggered-workflow.yml will run and process the data passed through the client_payload.
Using repository_dispatch to Trigger Cross-Repository Workflows
You can also use repository_dispatch to trigger workflows in a different repository. Here’s how:
Step 1: Set Up Workflow in the Target Repository
In the target repository, create a .github/workflows/target-workflow.yml file:
name: Target Workflow
on:
repository_dispatch:
types: "jenkins"
jobs:
run_external_event_action:
runs-on: devops-runner
steps:
- name: Step to check out the code
uses: actions/checkout@v2
- name: Step to run a script
run: |
echo "This workflow was triggered by an external repository_dispatch event" echo "Payload data: ${{ github.event.client_payload.version }}"Step 2: Trigger the Event from the Source Repository
In the source repository, you can trigger the event by sending a repository_dispatch API request to the target repository:
curl -X POST https://api.github.com/repos/<target_username>/<target_repository>/dispatches \ -H "Authorization: token <your_personal_access_token>" \ -d '{"event_type": "jenkins", "client_payload": {"version": "1.0.0"}}'Note: The authorization header must be in the Authorization: token xxxxxx format and not in bearer token format Authorization: Bearer xxxxxx.
The request body must contain the event_type entry which must match with one of the event types you defined in the workflow file e.g. build or publish. If the event type doesn’t match any configuration, then nothing happens, and your request passes silently. The API does not tell if a workflow was triggered.
Common Use Cases for repository_dispatch
Cross-repository automation: Trigger workflows in different repositories, such as when updating a shared library or deploying across multiple services.
External system triggers: Connect your GitHub repository with external tools (like monitoring systems, CI tools, or internal services) to trigger workflows based on external events.
Manual intervention: Sometimes, you might want to trigger a workflow on demand, like when you need to deploy something manually or trigger a series of tests after a change in a non-GitHub service.
Custom triggers: If you’re working with complex workflows, repository_dispatch allows you to define custom triggers that suit your business logic and process.
Best Practices
Authentication: Always use a GitHub Personal Access Token (PAT) for API requests. Be sure to only grant necessary permissions to avoid security risks.
Event Type Naming: Use descriptive event type names (event_type field) to make it easier to understand which workflows are triggered by which events.
Handle Custom Payloads: Ensure your workflows are set up to handle custom payload data properly and validate the data to prevent issues.
Rate Limits: Be mindful of GitHub’s API rate limits when triggering events frequently.
Conclusion
The repository_dispatch event in GitHub Actions is a powerful and flexible tool for integrating external systems, services, or other repositories into your workflows. It allows you to trigger workflows based on custom events and payloads, enabling a wide range of use cases, from cross-repository automation to external system triggers. By combining repository_dispatch with GitHub Actions, you can significantly extend the automation capabilities of your repository and streamline your development processes.
Kommentare