GitHub Actions工作流互触发及ref参数‘未找到’错误解决

开发者阿泽

2026-7-7

解决GitHub Actions触发workflow_dispatch时ref参数错误的问题

问题根源

refs/pull/<PR号>/merge是GitHub为PR动态生成的虚拟合并引用，并非仓库中实际存在的持久分支。而workflow_dispatch API要求传入的ref必须是仓库中可识别的实际分支引用或提交SHA，因此直接传递这个虚拟ref会导致"No ref found"错误。

可行解决方案

1. 使用PR的源分支引用

在pull_request事件触发的工作流中，GitHub提供了github.head_ref变量，对应PR的源分支名称（比如feature/my-feature）。将其拼接为标准分支引用格式传递：

- name: 触发下游workflow
  run: |
    curl -X POST \
      -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/${{ github.repository }}/actions/workflows/your-downstream-workflow.yml/dispatches \
      -d '{
        "ref": "refs/heads/${{ github.head_ref }}",
        "inputs": {
          # 按需传递下游工作流的输入参数
        }
      }'

这种方式直接指向PR的源分支，是仓库中实际存在的引用，API可以正确识别。

2. 使用PR的提交SHA（更可靠）

如果担心源分支后续被修改或删除，可以直接使用PR头部提交的SHA值，这个值是固定且唯一的：

- name: 触发下游workflow
  run: |
    curl -X POST \
      -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
      -H "Accept: application/vnd.github.v3+json" \
      https://api.github.com/repos/${{ github.repository }}/actions/workflows/your-downstream-workflow.yml/dispatches \
      -d '{
        "ref": "${{ github.event.pull_request.head.sha }}",
        "inputs": {
          # 按需传递下游工作流的输入参数
        }
      }'

使用SHA可以确保下游工作流基于PR提交的特定版本运行，不受后续分支变更影响。