GitHub Actions workflow_run 怎么接收上一个工作流的构建产物

把构建和发布拆成两个 GitHub Actions 工作流后，最容易踩的坑不是上传产物，而是下游工作流不知道该下载哪一次运行的产物。解决方法是：上游用 actions/upload-artifact 固定产物名，下游用 workflow_run 监听上游完成事件，再把 github.event.workflow_run.id 传给 actions/download-artifact。

官方文档：https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows

下面以构建工作流名为 Build、产物名为 dist-package 为例，只处理事件、运行记录和产物下载，不展开部署权限策略。

先把两个工作流的职责拆开

先在仓库的 .github/workflows 目录打开现有的构建工作流。在 GitHub 页面中进入 Actions → Build → 最近一次运行 → Artifacts，确认构建确实会上传一个稳定名称的产物。这里的名称就是下游下载时的匹配条件，不要每次用提交 SHA 临时拼出不同名称。

name: Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v6
      - name: Build package
        run: |
          # 把项目构建结果集中放到 dist，便于下游按一个产物下载。
          mkdir -p dist
          echo "build output" > dist/build.txt
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          # 这个名称必须与下游 download-artifact 的 name 完全一致。
          name: dist-package
          path: dist/

在同一仓库新建消费工作流时，菜单路径可以按 Actions → New workflow → set up a workflow yourself 进入编辑器，文件名例如 release-package.yml。这一步只准备入口，不要把构建步骤复制到第二个工作流。

让下游只监听 Build 的完成事件

消费工作流的触发器写成 workflow_run，并在 workflows 中写上游工作流的显示名称。types: [completed] 表示只在上游完成时触发；GitHub 官方说明还要求该工作流文件存在于默认分支，并且连续串联层级不能超过三层。

name: Release package

on:
  workflow_run:
    # 只接收名为 Build 的上游工作流，不按文件名猜测。
    workflows: [Build]
    types: [completed]

permissions:
  # 下载上游运行的 artifact 至少需要 Actions 读取权限。
  actions: read

jobs:
  consume:
    # 上游失败也会触发 completed，所以成功条件放到 job 上。
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - name: Download upstream artifact
        uses: actions/download-artifact@v5
        with:
          # name 锁定上游上传的产物，run-id 锁定具体一次运行。
          name: dist-package
          run-id: ${{ github.event.workflow_run.id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          path: ${{ runner.temp }}/dist-package
      - name: Show downloaded files
        run: |
          # 只列出下载目录，避免把整个 runner 工作区当成输入。
          find "${{ runner.temp }}/dist-package" -maxdepth 2 -type f -print

注意 workflow_run 的触发并不只针对成功：上游失败、取消等完成结论也会触发事件。因此把 conclusion == 'success' 放在 job 或 step 的条件中，能避免消费失败构建。

用上游运行 ID 下载同一份产物

这里的关键字段是 github.event.workflow_run.id，不是当前消费工作流自己的 github.run_id。前者指向刚刚完成的 Build 运行，后者指向 Release package 当前这一次运行。两者混用时，最常见的表现就是找不到产物，或者下载到了另一条运行记录的文件。

在 GitHub 页面中进入 Actions → Release package → 某次运行 → Summary → Artifacts，展开任务日志可以看到下载步骤；下载目录字段应与 YAML 中的 path 一致。若采用官方示例中的临时目录，后续步骤要继续使用同一个目录读取文件。

页面上按三处信息快速排查

如果只是同一个工作流里的上下游 job，优先用 needs 和普通的 download-artifact；只有跨工作流传递，才需要补上 workflow_run 的运行 ID。这样能减少事件链和排查范围。

常见问题

为什么下游工作流会触发，但下载不到文件？

先看上游运行是否真的成功，再确认产物名称完全一致，最后检查 run-id 是否来自 github.event.workflow_run.id。只写 name 而不写 run-id 时，跨工作流下载无法准确定位上游运行。

workflow_run 能不能连续串很多层？

官方事件说明限制了最多三层工作流串联。超过这个范围时，应把多个动作合并到较少的工作流中，或使用更直接的调度方式。