til/github-actions/trigger-a-workflow-via-an-api-call.md

Trigger A Workflow Via An API Call

We can set up a GitHub Actions workflow to run when triggered by an API call. This is done with the workflow_dispatch event.

First, we add workflow_dispatch to our workflow as a triggering event:

on:
  workflow_dispatch:

Second, we create a fine-grained personal GitHub access token that has permissions for dispatching to GitHub Actions. More details on that in the GitHub docs.

Then, we can use cURL or some other tool for issuing an HTTP POST request to the workflow dispatch API endpoint. The cURL request will look something like this:

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \
  -d '{"ref":"topic-branch","inputs":{"name":"Mona the Octocat","home":"San Francisco, CA"}}'

Note: we need to alter that URL with the OWNER and REPO that the workflow lives in as well as the WORKFLOW_ID which can be the name of the workflow file (e.g. my-dispatchable-workflow.yml).

This event also means that we can manually trigger the workflow from the GitHub Actions UI for that workflow.