GitHub Actions reusable workflow 传递矩阵参数

GitHub Actions 的 reusable workflow 传递矩阵参数，关键是把矩阵值写在调用方 job 的 with 中，而不是试图在被调用工作流里重新读取调用方的 matrix。被调用文件先用 on.workflow_call.inputs 声明输入，调用方再用 ${{ matrix.target }} 逐项传入。这样同一个工作流就能分别处理 dev、stage、prod 等目标。

官方地址：https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows

先把 reusable workflow 的输入契约写清楚

被调用文件位于仓库的 .github/workflows 目录，并通过 workflow_call 暴露参数。下面的例子把部署目标定义成必填字符串，正文中的注释只解释关键边界：

name: deploy-by-target

on:
  workflow_call:
    inputs:
      target:
        description: 部署目标，例如 dev 或 prod
        required: true
        type: string  # 调用方传入值的类型必须匹配

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Show target
        run: |
          # 只使用已声明的 inputs，避免依赖调用方的 matrix 上下文
          echo "部署目标：${{ inputs.target }}"

workflow_call.inputs 支持 boolean、number、string 三种类型。部署环境名通常用 string；不要把 dev 之类的文本误写成布尔值，也不要把输入名写成 matrix.target。输入名是契约字段，矩阵只是调用方的取值来源。

在调用方 job 上把矩阵值传给 with

矩阵策略和 uses 放在同一个调用 job 中，每个矩阵组合都会调用一次 reusable workflow。下面用三个环境说明传递关系：

name: release

on:
  workflow_dispatch:

jobs:
  deploy:
    strategy:
      fail-fast: false  # 一个环境失败时保留其他矩阵任务的结果
      matrix:
        target: [dev, stage, prod]
    uses: octo-org/example-repo/.github/workflows/deploy-by-target.yml@main
    with:
      target: ${{ matrix.target }}  # 每个矩阵任务传入自己的环境名
    secrets: inherit

这里不能把 uses 塞进 steps，因为 reusable workflow 是 job 级调用对象；调用 job 可使用的字段也比普通 job 少。若工作流还需要凭据，使用显式 secrets 或组织允许范围内的 secrets: inherit，不要把 token 写进 with。

需要回传结果时，补齐三层 outputs 映射

只传入参数不等于调用方自动得到结果。先让步骤写入 GITHUB_OUTPUT，再映射到 job，最后映射到 reusable workflow；调用方通过 needs.deploy.outputs 读取。

on:
  workflow_call:
    inputs:
      target:
        required: true
        type: string
    outputs:
      endpoint:
        description: 当前目标的服务地址
        value: ${{ jobs.deploy.outputs.endpoint }}  # workflow 层映射

jobs:
  deploy:
    runs-on: ubuntu-latest
    outputs:
      endpoint: ${{ steps.result.outputs.endpoint }}  # job 层映射
    steps:
      - id: result
        run: |
          # 示例只回传非敏感结果，真实密钥不能写入输出
          echo "endpoint=https://${{ inputs.target }}.example.test" >> "$GITHUB_OUTPUT"

调用方要先建立依赖关系，再读取结果：

  report:
    runs-on: ubuntu-latest
    needs: deploy  # 等待 reusable workflow 调用 job 完成
    steps:
      - run: |
          # 输出用于日志核对，不要把敏感值打印到日志
          echo "部署结果：${{ needs.deploy.outputs.endpoint }}"

如果 reusable workflow 本身使用矩阵，workflow output 并不是一个自动聚合的数组；官方规则是取最后一个成功完成且实际设置了值的矩阵任务。因此需要完整汇总时，应让每个任务上传 artifact，或在后续 job 中显式收集结构化结果。

用这张清单排查参数没有生效

常见问题

矩阵参数能直接在被调用工作流里读取 matrix.target 吗？

不能把调用方上下文当作输入契约。应在调用 job 的 with 中传值，被调用工作流统一从 inputs.target 读取。

为什么调用 reusable workflow 时不能添加普通 steps？

因为它占据一个 job 的调用位置，uses、with、strategy 等字段描述调用关系；需要额外命令时放到被调用工作流，或拆出前后置 job。

如何确认三个矩阵任务确实收到了不同参数？

在被调用工作流输出非敏感的目标名，并在运行摘要按目标核对；生产环境不要打印 token、密码或完整连接串。