Using Github Actions with Repository Dispatch Event

Sanjar Kairosh
December 6th, 20202 min read
Photo By James Harrison on Unsplash

Using Github Actions with Repository Dispatch Event

If you’ve ever set up a Github Actions workflow on a repository, you will recognize the YAML file that executes steps upon any code you push to the repository.

These steps could entail building and deploying your code for production, for instance.

name: Netlify

# Controls when the action will run. Triggers the workflow on push request, or repository dispatch
    branches: [main]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
  # This workflow contains a single job called "build"
    #  The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the jobs
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      - name: Setup Node.js environment
        uses: actions/setup-node@v2.1.2
          version: 12.x

      # Runs a set of commands using the runners shell
      - name: Build the site
        run: |
          npm install --production
          npm run productionbuild
      - name: Deploy To Netlify
        uses: nwtgck/actions-netlify@v1.1.11
          publish-dir: "./public"
          production-branch: main

          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Above we define the steps for Github Actions to build the code in a node environment and deploy it to Netlify. This workflow is for my Gatsby code for my website. But what happens if I want to trigger the steps above on events other than pushing code?

Invoking a Repository Dispatch Event From a CMS

I used Strapi CMS to manage content for my website. And I realized that I needed to trigger the workflow above every time I updated the content on Strapi. I needed to update my site every time I changed the content.

Into the picture came the amazing manual Repository Dispatch event. I realized I could use the Github API to let my Gatsby repository know it should build and deploy my updated site.

To trigger a repository dispatch one must send a POST request to the following Github API endpoint{owner}/{repo}/dispatches

The owner is your GitHub username, and the repo is the repository name.

I set the accept header parameter to application/vnd.github.v3+json and sent a body with the parameter event_type . This last parameter is required. You could also send other payloads with the body.

I had to create and use a personal Github token with the repo scope to obtain write access. Your repository dispatch will not be authorized otherwise. See here to learn more about creating a personal token on Github.

Once you’ve created the token, copy it and store it somewhere safe. You will not be able to access your Github token value after it has been created.

I added the token to the above POST request as the Authorization header parameter with the value:

`Bearer ${process.env.GITHUB_TOKEN}`

The entire POST request should look something like:

URL: https://api.github/com/repos/{owner}/{repo}/dispatches
Headers: {
    Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
    Accept: `application/vnd.github.v3+json`,
    Content-Type: `application/json`,
Body: {
    'event_type': 'custom_event_type'

Finally, I made sure to add the repository dispatch event type to the main.yml file

name: Netlify

# Controls when the action will run. Triggers the workflow on push request, or repository dispatch
    branches: [main]
    types: [custom_event_type]
# ...

Now, every time I update the content on Strapi and send the POST request above to the Github API, the repository_dispatch event is triggered and the workflow file is executed.


In my case, I had to trigger my Gatsby code build upon any changes to my content on Strapi. But the repository dispatch webhook could come in handy in all sorts of ways. I am excited to utilize it more in my future projects. Thanks for reading my article, I hope you find it helpful!


copyright ©2021 all rights reserved, Sanjar Kairosh
illusrations by icons8