A simple tutorial for creating externally triggered GitHub Actions workflows
GitHub actions support Webhook events as starting points for running a workflow
Most of these builtin events are tied to specific Gitub events, such as "deployment" or "milestone".
There is, however, a generic event that should be used to trigger a GitHub Actions workflow from an external source, named repository_dispatch
"repository_dispatch" has a property called "event_type" that can be invoked at the level of the workflow as a custom event, allowing for further granularity in multiple external calls for diferent workflows to the same repository.
It also allows for an optional "client_payload" property, that can store a JSON object that can be passed to the workflow.
At the level of the GitHub Actions workflow, this can be configured as:
name: Hello World Repo Dispatch
on:
repository_dispatch:
types: example-event
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: foo
run: echo ${{ github.event.client_payload.foo }}
Such workflow can be triggered by a POST request to the GitHub API, with Basic Authorization with GitHub username and password. The request body should include the "event_type" matching the one defined in the workflow, and an optional "client_payload".
POST https://api.github.com/repos/:owner/:repo/dispatches
{
"event_type": "example-event",
"client_payload": {
"foo": "bar"
}
}
An example using cURL:
curl -i -X POST 'https://api.github.com/repos/rgdiascardoso/github-actions-manual-trigger/dispatches' \
-u {{ username }}:{{ password }} \
-d '{"event_type": "example-event", "client_payload": {"foo":"bar"}}'
A possible better alternative in the long run is to issue a GitHub access token from "Settings\Developer Settings\Personal Access Tokens" and make the POST request with a Bearer Authorization header.
A successful request will be coded 204 No Content, without body.
Additional information on the "repository_dispatch" event can be found here