Webhook Triggers for GitHub Actions
Tags: github, ci
Published: 2020-06-18 13:01:11

# External Triggers for GitHub Actions

With [GitHub Actions](https://github.com/features/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](https://help.github.com/en/actions/reference/events-that-trigger-workflows) which are caused by certain activities on GitHub, e.g. a [push](https://help.github.com/en/actions/reference/events-that-trigger-workflows#push-event-push) to a repository or the creation of a new [issue](https://help.github.com/en/actions/reference/events-that-trigger-workflows#issues-event-issues). 
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](https://help.github.com/en/actions/reference/events-that-trigger-workflows#external-events-repository_dispatch) event is GitHub’s way to trigger a workflow from outside of GitHub. Every `repository_dispatch` event comes with an [event_type](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) 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:

```yaml
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](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event). 
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](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) with `repo` scope to call the GitHub API:

```bash
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](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idif) and [context expressions](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions) enable us to do so. 
The [github context](https://help.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context) gives us full access to the [repository_dispatch](https://developer.github.com/webhooks/event-payloads/#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:

```yaml
- 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](https://github.com/s1h-org/actions-webhook).
However, given the large amount of events we can process via GitHub Actions there is a huge potential yet to explore!