External Triggers for GitHub Actions

With GitHub Actions we have a really powerful tool at our hands to automate our workflows on GitHub.
Actions are deeply integrated with GitHub and allow us to run CI / CD pipelines, automate tasks to manage issues or to connect our repo with third-party services.
Workflows are triggered on events which are caused by certain activities on GitHub, e.g. a push to a repository or the creation of a new issue.
However, GitHub may not be our only source of events to trigger a workflow, so let’s see how we can trigger a workflow via web hook.

repository_dispatch

A repository_dispatch event is GitHub’s way to trigger a workflow from outside of GitHub. Every repository_dispatch event comes with an event_type property which allows us to limit our workflow execution to certain events. By default, every web hook call would trigger a workflow run.

Supported events are listed in our workflow file on the repository_event trigger:

name: webhook-trigger

on:
  repository_dispatch:
    types: 
      - webhook-one
      - webhook-two
      - your-custom-event-type

Webhook Trigger

repository_dispatch events are created via GitHub API.
We’re required to provide an event_type property, which corresponds to one of our configured repository_dispatch types above. It is also possible to pass additional payload via client_payload JSON object. This way we’re able to process additional data in our workflow.

Issuing a repository_dispatch event requires a personal access token with repo scope to call the GitHub API:

curl -H "Authorization: token <YOUR_GITHUB_TOKEN>" \
    --request POST \
    --data '{"event_type": "<YOUR_EVENT_TYPE>"}' \
 https://api.github.com/repos/<YOUR_GITHUB_USER>/<YOUR_GITHUB_REPO>/dispatches

Processing Event Types

Let’s assume we want to carry out different workflow steps, depending on the event_type. Conditionals and context expressions enable us to do so.
The github context gives us full access to the repository_dispatch payload, which stores our event_type value as action property.

So we’re able to bind workflow steps to the trigger event type:

- name: Event Name
  run: |
    echo "Event triggered by $GITHUB_EVENT_NAME"
    echo "Dispatch type ${{ github.event.action }}"
- name: Goodbye
  if: ${{ github.event.action == 'webhook-one' }}
  run: npx cowsay "Bye!"
- name: Adiós
  if: ${{ github.event.action == 'webhook-two' }}
  run: npx cowsay "Adiós!

The client_payload is also accessible via context expression, e.g.

${{ github.event.client_payload.unit }}

Conclusion

It took me a bit to put all pieces together, but once all dots were connected, GitHub Actions integrated smoothly in existing CI infrastructure via web hooks.
A small sample is available in this repo.
However, given the large amount of events we can process via GitHub Actions there is a huge potential yet to explore!