Learn how to trigger GitHub Actions workflows using the repository_dispatch event for external API integrations. Understand why it’s the best choice for triggering workflows from outside GitHub.
Table of Contents
Question
You need to trigger a workflow using the GitHub API for activity that happens outside of GitHub. Which workflow event do you use?
A. check_suite
B. workflow_run
C. deployment
D. repository_dispatch
Answer
D. repository_dispatch
Explanation
The correct workflow event to use when you need to trigger a GitHub Actions workflow from an activity outside of GitHub is repository_dispatch. This event is specifically designed to allow external systems, such as APIs or webhooks, to communicate with and trigger workflows in a GitHub repository.
Why Choose repository_dispatch?
- Customizable Event Types: The repository_dispatch event allows you to define custom event types (event_type) that can be tailored to your specific use case. This flexibility makes it ideal for integrating external tools or APIs.
- External Triggering via API: You can trigger this event by making a POST request to the GitHub API endpoint /repos/{owner}/{repo}/dispatches. This is useful for scenarios where external systems need to initiate workflows.
- Payload Support: It supports sending a JSON payload (client_payload) with additional data that can be accessed within the triggered workflow, enabling dynamic and context-aware operations.
- Cross-Repository Compatibility: It can trigger workflows in other repositories, making it suitable for multi-repository setups.
Example Use Case
Imagine you have an external monitoring tool that detects a critical issue and needs to trigger a remediation workflow in your GitHub repository. By configuring the repository_dispatch event, the tool can send a webhook or API call to start the workflow automatically.
How to Configure repository_dispatch
In Your Workflow File:
Add the following configuration to your .github/workflows/*.yml file:
on:
repository_dispatch:
types: [custom-event-type]
jobs:
handle-dispatch:
runs-on: ubuntu-latest
steps:
- name: Print Payload
run: echo ${{ github.event.client_payload }}
Replace custom-event-type with your desired event name.
Triggering via API:
Use a POST request with a personal access token (PAT) to trigger the event:
curl -X POST \
-H "Accept: application/vnd.github.v3+json" \
-H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
https://api.github.com/repos/username/repo-name/dispatches \
-d '{"event_type":"custom-event-type","client_payload":{"key":"value"}}'
Other Options Explained
A. check_suite: Triggers workflows based on check suite events, which are related to CI/CD checks—not suitable for external triggers.
B. workflow_run: Runs workflows in response to the completion of another workflow—not designed for external activities.
C. deployment: Used for deployment-related events, typically tied to GitHub’s native deployment features—not applicable for general external triggers.
By using repository_dispatch, you gain full control over triggering workflows from external systems, making it the most appropriate choice for this scenario.
The repository_dispatch event allows you to trigger a workflow in response to external activity. It is commonly used when you need to trigger a workflow from outside GitHub, such as from another system or service, by sending a request to the GitHub API. This event provides flexibility to integrate with various external systems and trigger workflows in a GitHub repository.
GitHub Actions certification exam assessment practice question and answer (Q&A) dump including multiple choice questions (MCQ) and objective type questions, with detail explanation and reference available free, helpful to pass the GitHub Actions exam and earn GitHub Actions certification.