In this article, I’ll show you how to set up a webhook trigger on a GitHub repository, configure the notification on Kontent.ai, and adjust the request to match GitHub’s requirements.

GitHub Pages and GitHub Actions

It’s been a while since GitHub allowed us to host static files on their servers. In fact, we’ve been hosting our site Kentico Advantage built with Gatsby on GitHub Pages for over two years now. The site build was configured on Travis CI that also took care of deploying to Pages.

GitHub Actions are similar to any other CI tool, but they come with one great advantage. In terms of functionality, they are not closed to the community. As part of your build process, you can use a function that someone else created, and here comes the cool stuff, just by referencing its codebase.

Why is that cool? Because if you’re missing something in the CI tool, you no longer need to work around it or vote on feature requests. Just implement it or use someone else’s implementation.

GitHub Action Workflow of a Gatsby site

While the feature is called GitHub Actions, the actual build process is called Workflow. Let’s take a look at what the workflow configuration looks like for our Gatsby site:

name: Site build

# workflow triggers
on:
  push:
    branches: [ source ]
  pull_request:
    branches: [ source ]
  workflow_dispatch:

# build process
jobs:
  build:
    name: Build
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2.3.1

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: '14.x'
    
    - run: |
        npm ci
        npm run build

    - name: Deploy 🚀
      if: github.ref == 'refs/heads/source'
      uses: JamesIves/github-pages-deploy-action@4.1.1
      with:
        branch: master
        folder: public
        clean: true

It has two parts—triggers and the actual build process. This workflow can be started by pushing, submitting a pull request to the target branch source, or manually triggering the build from the GitHub UI.

The build job runs the Gatsby build and uses an action implemented by Jameslves to deploy a generated site to GitHub Pages (that is the Continuous Delivery part of the process).

Adding webhook trigger to GitHub Action

The push and PR triggers solve the need for build in case of code changes. Let’s now add a section after existing triggers that will allow us to start the workflow using a webhook notification:

# workflow triggers
on:
  push:
    branches: [ source ]
  pull_request:
    branches: [ source ]
  workflow_dispatch:

  # Allows external webhook trigger
  repository_dispatch:
    types:
      - webhook

The trigger is called repository_dispatch and you can limit the scope to only specific webhooks with a type. The type can be anything; “webhook” is just something I made up, and for this repo, it’s actually redundant—there’s only a single workflow on top of a single app codebase. However, this can be very useful for monorepos.

To test invoking this trigger, you need to send a special POST request to the following URL:

https://api.github.com/repos/{owner}/{repo}/dispatches

The request also needs to contain the following headers:

"Accept": "application/vnd.github+json"
"Authorization": "token {personal token with repo access}"

You need to provide a personal GitHub token with the repo access scope. If your trigger also features a type, specify it in the request body:

{"event_type": "webhook"}

Configuring webhook in Kontent.ai

A Gatsby site needs to be rebuilt every time new content is published or unpublished. Create a new webhook and configure it this way:

The last step is to decorate the webhook with the required headers. You can achieve this by implementing a simple serverless function, but there’s also a no-code way using Pipedream, Zapier, or another similar service.

Proxy webhooks through Pipedream

On Kentico Advantage, we’re using Pipedream. The workflow trigger is of the “Webhook” type, and it does not require any configuration, just confirmation of the default values. As soon as you create it, you will get the trigger URL (1):

Use it as the target URL of your Kontent webhook. Then add another step (2) to your Pipedream workflow and again select a Webhook type. The URL is the GitHub Actions URL mentioned earlier: https://api.github.com/repos/{owner}/{repo}/dispatches. Don’t forget to specify the POST method and the required headers:

When you’re finished, remember to Deploy and enable your workflow. I always forget to do the latter 😊.

Bonus: Cancel previous builds to avoid build stacking

Now the workflow is triggered after every content publish and unpublish events. On small projects like our Advantage website, it’s fine, but on a larger scale, you can end up with stacking builds. If there are multiple content items published during a small timeframe, there will be multiple builds running simultaneously.

Add the auto-cancel-redundant-workflow job before the actual build job to cancel all previously triggered builds that are still in progress:

jobs:
  pre-job:
    name: Pre-job
    runs-on: ubuntu-latest

    steps:
    
      - uses: technote-space/auto-cancel-redundant-workflow@v1

      - name: Cancel redundant workflows
        run: echo "Cancel redundant workflows finished"

  build:
    ...

Conclusion

In this article, I showed you how to build a Gatsby site, deploy it to GitHub Pages, trigger the workflow from an external webhook, and cancel redundant builds caused by frequent content changes. GitHub Actions are a powerful tool and finally allow us, developers, to have everything under one GitHub roof.

Are you having issues with GitHub Actions? Get in touch on our Discord.