GitHub Actions：如何根据矩阵值条件触发可重用工作流

问题背景 #

通过Python脚本generate_matrix.py生成了如下矩阵配置文件output.json：

{"include": [{"foo": "foo1","bar": "bar1","path": "path1"},{"foo": "foo2","bar": "bar2","path": "path2"}]}

尝试在GitHub Actions工作流的Trigger_Job中使用if: ${{ matrix.path }} == 'path1'控制仅当path为path1时触发可重用工作流，却收到报错：

"The workflow is not valid. ...: Unrecognized named-value: 'matrix'. Located at position 1 within expression: matrix.path"

且不想通过给可重用工作流新增参数解决，需要替代方案。

解决方案 #

方案1：将Trigger_Job设为矩阵作业，在作业级别过滤 #

GitHub Actions的matrix变量仅存在于启用了strategy.matrix的作业上下文中。可以先将Trigger_Job配置为矩阵作业，加载生成的矩阵数据后，通过作业级if条件过滤目标项：

首先，确保生成矩阵的作业（比如generate_matrix）将output.json的内容输出为GitHub Actions步骤输出：

jobs:
  generate_matrix:
    runs-on: ubuntu-latest
    steps:
      - name: Generate matrix
        run: python generate_matrix.py
      - name: Export matrix as output
        run: echo "matrix_json=$(cat output.json)" >> $GITHUB_OUTPUT
    outputs:
      matrix_json: ${{ steps.generate_matrix.outputs.matrix_json }}

然后在Trigger_Job中加载矩阵并过滤：

Trigger_Job:
    needs: generate_matrix
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJson(needs.generate_matrix.outputs.matrix_json) }}
    if: ${{ matrix.path == 'path1' }}
    steps:
      - uses: your/reusable-workflow@v1
        # 可按需传递矩阵中的其他变量
        with:
          foo: ${{ matrix.foo }}
          bar: ${{ matrix.bar }}

方案2：在生成矩阵时直接过滤目标项 #

修改generate_matrix.py的逻辑，仅保留path为path1的项到输出文件中，这样工作流无需额外条件判断即可直接使用过滤后的矩阵：

import json

# 原始矩阵数据
original_matrix = {"include": [{"foo": "foo1","bar": "bar1","path": "path1"},{"foo": "foo2","bar": "bar2","path": "path2"}]}
# 过滤出path为path1的项
filtered_matrix = {"include": [item for item in original_matrix["include"] if item["path"] == "path1"]}

# 写入输出文件
with open("output.json", "w") as f:
    json.dump(filtered_matrix, f)

之后工作流中直接加载这个已过滤的矩阵即可，无需添加if条件。

报错原因说明 #

matrix是GitHub Actions的矩阵作业上下文变量，仅在定义了strategy.matrix的作业内部可用。如果Trigger_Job未配置矩阵策略，或者条件写在矩阵作业上下文之外（比如工作流级别），就会出现"Unrecognized named-value: 'matrix'"的错误。

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