Ringing the Doorbell of your GitHub Repository with ‘repository_dispatch’

2 min readOct 16, 2023

On my recent exploration of GitHub Actions, I was drawn to the vast world of workflow triggers. These triggers are the heartbeats of automation in GitHub, determining when and why certain automations, known as workflows, should run. One trigger that stood out is repository_dispatch. This trigger is particularly useful for scenarios when you need to run workflows based on events that happened outside of GitHub.

The Special Doorbell

Imagine a modern home equipped with a doorbell unlike any other. Instead of just alerting residents of a visitor, it allows that visitor to convey specific requests. Now, visualize the repository_dispatch in the same light, acting as this unique doorbell, always awaiting the special signal from the outside.

Setting Up The Doorbell

For repository_dispatch to be operational, it needs to be defined in your GitHub Actions workflow. A simple configuration could look like this:

on:
  repository_dispatch:
    types: [event_type_1, event_type_2]

This tells your repository to keep an ear out for external repository_dispatch events labeled as event_type_1, event_type_2.

Ringing The Doorbell: External Systems in Play

When an external entity, be it an app or another system, aims to initiate a workflow in your repo, it does so by sending a POST request to GitHub’s API. This is how that “doorbell ring” is conveyed:

curl -X POST \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.everest-preview+json" \
  "https://api.github.com/repos/OWNER/REPO/dispatches" \
  -d '{"event_type": "event_type_1"}'

The Action Begins

One this external signal is received, your repository responds swiftly. The workflow linked to the dispatched event type fires up.

Why is This Useful?

What makes repository_dispatch a gem is its ability to connect your GitHub repository with external events seamlessly. This open doors to richer integrations, streamlining complex processes, especially in advanced CI/CD setups or when coordinating with third-party tools.

Conclusion

To wrap up, just as modern homes evolve with advanced doorbells and automation, so does GitHub with features like repository_dispatch, enhancing the communication and responsiveness of repositories.

My exploration into repository_dispatch is a subset of the larger universe of workflow triggers in GitHub Actions. Anticipate a future post where we’ll dive deeper into various triggers, their technical nuances, and their applications in real-world scenarios.