Triggering GitHub Actions Using Repository Dispatches

TL;DR: Using HTTP requests, you can send repository dispatches to trigger GitHub Actions workflows

GitHub Actions is a quickly growing and quickly developing CI/CD platform that is free to all GitHub users. While the platform is still relatively young, features are being released constantly by the Actions team and the community of developers utilizing the platform and developing open source actions for it continues to expand.

One feature that has been at the front of many current and potential users minds is the flexibility of triggering actions. Unsurprisingly, triggering actions based on commits, releases, and branches is simple to configure. GitHub has also made it easy to schedule tasks using cron notation. What becomes less obvious, though, is how users could either manually trigger an action or have a third party service trigger an action. Other platforms like Jenkins make this simple with the ability to build jobs from the click of a button in their web console, or by installing plugins that enable remote services to act as triggers.

While GitHub actions does not yet have a similar feature in their web console, this functionality does exist in the form of repository dispatches. A repository dispatch is essentially just an HTTP request to your repository asking GitHub to kick off any action or webhook. Using this feature, you can both manually trigger GitHub actions using repository dispatches, or you can set up an application to trigger the action by sending a request.

Setting up your action

In your workflow yml file, you need to add a trigger for the on key that says that the workflow will accept repository dispatches.

The simplest configuration is to have the workflow trigger on any repository dispatch:

on:
    repository_dispatch:

If you have multiple workflows that might be triggered by separate dispatches, however, you can specify specific event types that will trigger the workflow.

on:
    repository_dispatch:
        types: [start-example-workflow]

In the above example, only dispatches with the event type "start-example-workflow" will trigger the workflow.

Custom Parameters

Throughout your action, you can also use information provided by the "client-payload" of the dispatch. Using the expression

${{ github.event.client_payload.example-key }}

will give you access to all of the data provided in the client payload. This will allow you to use the data as environment variables for bash commands or as inputs to other actions.

Constructing the request

The payload of a repository dispatch is quite simple:

{
    "event_type": "my_event_type",
    "client_payload": {
        "example-key": "example-value"
    }
}

This request also needs the following set of headers:

Accept:  application/vnd.github.everest-preview+json
Content-Type: application/json
Authorization: Bearer {{personal_access_token}}

At this point, I should clarify that in order to trigger the workflow, the request must be authenticated with a personal access token for a user that is authorized to access the repository.

To create an access token, follow these steps from GitHub and be sure that you have given the token access to the repo scope.

With that payload, you can POST the request to https://api.github.com/repos/:owner/:repo/dispatches to trigger workflows that are set up to accept the dispatch.

Using Postman

If your goal is to simply trigger these workflows with a push of a button, Postman might be one of the easiest ways to set up these POST requests and send them GitHub.

The first step is to create a new environment in Postman to store your personal access token. To do this, click the gear in the upper right hand corner to manage environments and create a new environment called GitHub.

From there, you should add a new environment with your personal access token as the variable token.

Once this environment is set up, you can now create a new collection of requests that will trigger your GitHub Actions workflows. To use the token that is a part of your environment, make sure your environment is selected in the upper right hand corner of your application, and then add the token to the Bearer Authorization of your request.

Next set the appropriate headers.

You can now set the appropriate payload for your dispatch and send the request. If everything is appropriately set up, you should get a 204 No Content Response.

Finally, you can save the request and send the dispatch whenever you want to manually trigger the workflow.

What's next?

Given that these triggers are simple HTTP Requests, you can obviously take advantage of this feature to integrate your actions with third party services. In the next article, we'll investigate strategies to trigger actions with integrations from services such as Slack and Sanity.io, a configurable CMS.