如何通过GitHub REST API的HTTP请求触发GitHub Action工作流？

前提条件 #

• 仓库.github/workflows/目录下存在可被触发的工作流YAML文件
• 生成拥有repo（私有仓库）或public_repo（公开仓库）权限的GitHub个人访问令牌（PAT），用于API请求身份验证

步骤1：配置工作流文件 #

要让工作流支持API触发，需在on字段中添加对应触发事件：

示例1：支持手动/API触发的workflow_dispatch #

name: API可触发工作流
on:
  workflow_dispatch:
    inputs:
      deploy-env:
        description: '目标部署环境'
        required: true
        default: 'staging'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 输出部署信息
        run: echo "开始部署到 ${{ github.event.inputs.deploy-env }} 环境"

示例2：支持外部触发的repository_dispatch #

name: 外部API触发工作流
on:
  repository_dispatch:
    types: [start-build] # 自定义事件标识，需和API请求中的event_type匹配
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 执行构建任务
        run: echo "收到外部API触发，启动构建流程"

步骤2：用curl命令触发工作流 #

触发workflow_dispatch事件 #

替换以下占位符：OWNER（用户名/组织名）、REPO（仓库名）、WORKFLOW_ID（工作流文件名或ID）、PAT（你的个人访问令牌）

curl -X POST \
  -H "Authorization: token ${PAT}" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches \
  -d '{"ref":"main","inputs":{"deploy-env":"production"}}'

• ref指定工作流执行的分支/标签/提交SHA，必须是仓库中存在的引用

触发repository_dispatch事件 #

替换对应占位符，event_type需和工作流中定义的types一致：

curl -X POST \
  -H "Authorization: token ${PAT}" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"start-build","client_payload":{"note":"来自本地curl的触发请求"}}'

验证触发结果 #

触发后可直接在仓库的「Actions」页面查看工作流的运行状态和日志。

内容的提问来源于stack exchange，提问作者Volodya Lombrozo