How to Trigger GitHub Actions Remotely

Usually, we need to perform some operation on GitHub in order to trigger a GitHub Action. This post introduces a way to trigger a GitHub Action remotely through an API call.

1. Common Ways to Trigger a GitHub Action

Here is an example GitHub Action:

1
2
3
4
5
6
7
name: GitHub Actions Demo
on: [push, pull_request]
jobs:
  Explore-GitHub-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World!"

What is defined under the on keyword are the events that trigger the Workflow. Here are several commonly used GitHub Action events:

workflow_dispatch, manual trigger

You can add interactive parameters in inputs (optional).

1
2
3
4
5
6
7
on:
  workflow_dispatch:
    inputs:
      name:
        description: "Person to greet"
        required: true
        default: "Mona the Octocat"

push, pushing code

1
on: push

issues, the issues lifecycle

1
2
3
on:
  issues:
    types: [opened, edited, milestoned]

issue_comment, issue comments

1
2
3
on:
  issue_comment:
    types: [created, deleted]

project, the project management lifecycle

1
2
3
on:
  project:
    types: [created, deleted]

pull_request, the PR lifecycle

1
2
3
on:
  pull_request:
    types: [assigned, opened, synchronize, reopened]

These event hooks can be used to automate many workflows.

2. Triggering a GitHub Action Remotely with the API

2.1 Creating a Token

Visit https://github.com/settings/tokens/new to apply for a Token.

You need to check the repo permission.

2.2 Adding the Workflow

In the repository https://github.com/shaowenchen/wait-webhook-to-run, create a new file .github/workflows/worker.yml. Its contents are as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
on:
  repository_dispatch:
    types:
      - webhook-1
      - webhook-2

jobs:
  run:
    runs-on: ubuntu-latest

    steps:
    - name: Hello World
      run: |
        echo Hello World!

In the types of repository_dispatch, you can define custom event types.

2.3 Triggering the GitHub Action Remotely

Here is the API call format:

1
2
3
4
curl -X POST https://api.github.com/repos/:owner/:repo/dispatches \
    -H "Accept: application/vnd.github.everest-preview+json" \
    -H "Authorization: token TRIGGER_TOKEN" \
    --data '{"event_type": "TRIGGER_EVENT"}'

Here, owner is the username, repo is the repository name, TRIGGER_TOKEN is the Token credential applied for above, and TRIGGER_EVENT is the custom event name.

Triggering the webhook-1 event

1
2
3
4
curl -X POST https://api.github.com/repos/shaowenchen/wait-webhook-to-run/dispatches \
    -H "Accept: application/vnd.github.everest-preview+json" \
    -H "Authorization: token ghp_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
    --data '{"event_type": "webhook-1"}'

Triggering the webhook-2 event

1
2
3
4
curl -X POST https://api.github.com/repos/shaowenchen/wait-webhook-to-run/dispatches \
    -H "Accept: application/vnd.github.everest-preview+json" \
    -H "Authorization: token ghp_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
    --data '{"event_type": "webhook-2"}'

Checking the GitHub Action run:

3. References

https://docs.github.com/cn/actions/reference/events-that-trigger-workflows