Using GitHub Actions to trigger Actions across repos

We have a mono-repo of our internal Node Packages. We use these to share code between teams. Some of these serve simple functions like our logger, up to more complex functionality like getting data from several sources and joining them together. 

We publish these to a private NPM. These are used across many repos and teams. We often make updates to these underlying packages, like enhance our logger, add a new data sources, refine a queries etc.

Unfortunately, changes mean we then have to manually upgrade packages in each repo to the newly published version, run tests, create PRs, get it approved and deploy. This can even impact timelines on projects, taking a developer out just for a package upgrade that came from another team can be one less thing that derails estimates.

In this post, I’ll show you how one GitHub Actions workflow from a repository can invoke a workflow in a different repository.

Events that trigger workflows

There are several git events that can trigger GitHub Action workflows. Most commonly push, pull_request and schedule. As you would regularly want your workflows to trigger when certain events happen on the repository, these common events cover these use cases. However, sometimes this is not enough, and you require a workflow trigger to respond to an external event.

This is where the repository_dispatch event comes in. 

repository_dispatch

In order to trigger this event, you need to send a HTTP POST request to an endpoint `https://api.github.com/repos/:owner/:repo/dispatches`.

This endpoint expects 2 parameters:

• event_type: This will be received in the workflow event as the action.

• client_payload: a JSON object with any params that you want to use in the workflow, this will be received in the client_payload of the event.

In order to be able to use the endpoint, you will need to be authenticated and authorized to access the receiver repository. For that purpose, you can create a personal access token and store in the GitHub secrets of the dispatching repository as AUTH_TOKEN .

The endpoint can be then invoked by using cURL:

Alternatively, you could use a plugin such as peter-evans/repository-dispatch.

How it works, an example

Repository A contains the “initiating” workflow, the dispatcher. It will be triggered on merge to main.

Now, every time you merge to `main` you will have an action that runs and sends a notification to repository B and repository C as defined in the matrix.

Repository B (and C) contains the “receiver” workflow. It will be triggered on repository_dispatch.

Conclusion

We use the dispatcher after publishing a new version of any one of our node packages to NPM. The publish completes, we then send an event to all repos defined in the matrix that a package has updated. These repos then consume this event, run a yarn upgrade package-x and generating a Pull Request. The Pull Request is tested, reviewed and merged by the code owners of that repo.

Now we can make continuous improvements without the risk of package updates affecting projects without testing, they can easily be rolled back and they are isolated from actual project work deployments for other teams.

The views expressed on this blog post are mine alone and do not necessarily reflect the views of my employer, Optus Administration Pty Ltd