Setting up Webhooks for Github Actions

Quick Guide on How to Trigger a Github Action via Webhooks

August 27, 2019

Github Actions are a pretty new feature to Github. CI is commonly used to automate building and running tests in software projects. However, there are other uses cases related to automation that benefit from CI. In this post I will be covering how to set-up Webhook that can kick-off a Github Action.

Just to clarify why it may be useful to kick off a build on demand via an http request consider the following examples.

Example 1: Triggering an Action to deploy a new version to production after a manual QA, steakholder review, or scheduled manual release.

Example 2: Triggering an Action to build and/or publish an updated version of a static site with content from a headless CMS API like Prismic, Contentful, or Ghost.

Example 3: Triggering an Action to generate and commit a changelog file to back into the code repository.

Getting Started

Three things are needed to be able to setup a webhook.

  • Github Action to Recieve & Process the Event
  • Personal Github Access Token
  • External trigger to kick off the webhook

Github Action

When setting up our Action, there is a single requirement that the on value of our workflow must include repository_dispatch. It can be part of a list of values, or it can be standalone.

If the repository is only ever expected to have a single webhook of this type, it is enough, all invocations will be processed by this workflow.

However we may want to distinguish between different webhooks to the same repository. To do that we need to make use of the event payload provided to the build. This information is stored on the github object within our workflow.

github.event.action corresponds to the event_type used in the payload of the trigger webhook, more on this below.

For now a template workflow file for our action would look like the file below:

name: Webhook Example
on: repository_dispatch
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    
    - name: On my_custom_webhook do ABC...
      if: github.event.action == 'my_custom_webhook'
      run: |
        echo "Hello From my_custom_webhook...doing ABC"
        
    - name: On my_custom_webhook do XYZ...
      if: github.event.action == 'my_custom_webhook_2'
      run: |
        echo "Hello From my_custom_webhook_2...doing XYZ"

The Action runs invocations of the respository_dispatch webhook in to the repository and within the last two steps are running conditionally on the value of event.action provided by our webhook.

This way we can take certain build steps on different events.

Personal Access Token

Before we can trigger our Action via a webhook, we need to obtain a personal access token to use. Follow this guide here: Creating a Personal Access Token for the Command Line . Only repo persmission seems to be needed to trigger the Actions at this time.

Once we an access token we’ll need to be sure to include it in the headers of the webhook request as Authorization: token TOKEN_VALUE_HERE.

Triggering the Github Action

Lastly, we’re ready to trigger our Action. We’ll be doing this via curl for this post.

The request we need to make it to the https://api.github.com/repos/:owner/:repo/dispatches. Where :owner is the account that owns the repository, and :repo is the name of repository containign the Github Action.

As for header we’ll need to include an Accept header with a custom value: application/vnd.github.everest-preview+json and Authorization with our access token.

Lastly, we need to include a json payload with event_type property, that can be read as github.event.action from our Action workflow.

Putting it all together looks something like this:

curl -X POST https://api.github.com/repos/:owner/:repo/dispatches \
-H 'Accept: application/vnd.github.everest-preview+json' \
-H 'Authorization: token TOKEN_VALUE_HERE' \
--data '{"event_type": "CUSTOM_ACTION_NAME_HERE"}'

Note that CUSTOM_ACTION_NAME_HERE corresponds to my_custom_webhook and my_custom_webhook_2 in our example workflow yaml above. The value can be any string.

At this point running the curl command should cause an Action workflow to run for the repository on Github.

Note: At the time of writing the dispatches API seems to be in preview/experimental release, so it may change in the future.

Conclusion

This post has been a quick guide on how to wire up a webhook to trigger a Github Action workflow. Having Actions be triggerable from ourside of the typical git workflow can be a valuable tool in the automation of common processes.

Further Reading & References