关于矩阵策略
使用矩阵策略,可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。 例如,可以使用矩阵策略在某个语言的多个版本或多个操作系统上测试代码。
向工作流程作业添加矩阵策略
使用 jobs.<job_id>.strategy.matrix
定义不同作业配置的矩阵。 在矩阵中,定义一个或多个变量,后跟一个值数组。 例如,以下矩阵有一个称为 version
的变量,其值为 [10, 12, 14]
,以及一个称为 os
的变量,其值为 [ubuntu-latest, windows-latest]
:
jobs:
example_matrix:
strategy:
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
将针对变量的每个可能组合运行作业。 在此示例中,工作流将运行六个作业,其中一个作业用于每个 os
和 version
变量组合。
上述矩阵将按以下顺序创建作业。
{version: 10, os: ubuntu-latest}
{version: 10, os: windows-latest}
{version: 12, os: ubuntu-latest}
{version: 12, os: windows-latest}
{version: 14, os: ubuntu-latest}
{version: 14, os: windows-latest}
有关参考信息和示例,请参阅 GitHub Actions 的工作流语法。
使用上下文创建矩阵
若要创建包含有关工作流程运行、变量、运行器环境、作业和步骤的信息的矩阵,请使用 ${{ <context> }}
表达式语法访问上下文。 有关上下文的详细信息,请参阅“上下文参考”。
例如,以下工作流触发事件 repository_dispatch
,并使用事件有效负载中的信息来生成矩阵。 使用如下所示的有效负载创建存储库调度事件时,矩阵 version
变量的值为 [12, 14, 16]
。 有关 repository_dispatch
触发器的详细信息,请参阅“触发工作流的事件”。
{
"event_type": "test",
"client_payload": {
"versions": [12, 14, 16]
}
}
on:
repository_dispatch:
types:
- test
jobs:
example_matrix:
runs-on: ubuntu-latest
strategy:
matrix:
version: ${{ github.event.client_payload.versions }}
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.version }}
展开或添加矩阵配置
若要扩展现有矩阵配置或添加新配置,请使用 jobs.<job_id>.strategy.matrix.include
。 include
值是一个对象列表。
例如,考虑以下矩阵。
strategy:
matrix:
fruit: [apple, pear]
animal: [cat, dog]
include:
- color: green
- color: pink
animal: cat
- fruit: apple
shape: circle
- fruit: banana
- fruit: banana
animal: cat
这将生成具有以下矩阵组合的六个作业。
{fruit: apple, animal: cat, color: pink, shape: circle}
{fruit: apple, animal: dog, color: green, shape: circle}
{fruit: pear, animal: cat, color: pink}
{fruit: pear, animal: dog, color: green}
{fruit: banana}
{fruit: banana, animal: cat}
每个 include
条目都按以下方式应用。
{color: green}
添加到所有原始矩阵组合,因为它可以添加,而不会覆盖原始组合的任何部分。{color: pink, animal: cat}
仅将color:pink
添加到包含animal: cat
的原始矩阵组合中。 这会覆盖上一个include
条目添加的color: green
。{fruit: apple, shape: circle}
仅将shape: circle
添加到包含fruit: apple
的原始矩阵组合中。{fruit: banana}
添加到任何原始矩阵组合时都会覆盖值,因此会将其作为其他矩阵组合进行添加。{fruit: banana, animal: cat}
添加到任何原始矩阵组合时都会覆盖值,因此会将其作为其他矩阵组合进行添加。 它不会添加到{fruit: banana}
矩阵组合中,因为该组合不是原始矩阵组合之一。
有关参考和示例配置,请参阅 GitHub Actions 的工作流语法。
排除矩阵配置
若要移除矩阵中定义的特定配置,请使用 jobs.<job_id>.strategy.matrix.exclude
。
例如,以下工作流将运行 9 个作业:每 12 个配置一个作业,再减去一个与 {os: macos-latest, version: 12, environment: production}
匹配的排除作业,以及两个与 {os: windows-latest, version: 16}
匹配的排除作业。
strategy:
matrix:
os: [macos-latest, windows-latest]
version: [12, 14, 16]
environment: [staging, production]
exclude:
- os: macos-latest
version: 12
environment: production
- os: windows-latest
version: 16
runs-on: ${{ matrix.os }}
有关参考信息,请参阅 GitHub Actions 的工作流语法
使用输出定义两个矩阵
可使用一个作业的输出来定义多个作业的矩阵。
例如,以下工作流演示了如何在一个作业中定义值的矩阵,在第二个作业中使用该矩阵生成项目,然后在第三个作业中使用这些项目。 每个项目都与矩阵中的值相关联。
name: shared matrix on: push: workflow_dispatch: jobs: define-matrix: runs-on: ubuntu-latest outputs: colors: ${{ steps.colors.outputs.colors }} steps: - name: Define Colors id: colors run: | echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT" produce-artifacts: runs-on: ubuntu-latest needs: define-matrix strategy: matrix: color: ${{ fromJSON(needs.define-matrix.outputs.colors) }} steps: - name: Define Color env: color: ${{ matrix.color }} run: | echo "$color" > color - name: Produce Artifact uses: actions/upload-artifact@v4 with: name: ${{ matrix.color }} path: color consume-artifacts: runs-on: ubuntu-latest needs: - define-matrix - produce-artifacts strategy: matrix: color: ${{ fromJSON(needs.define-matrix.outputs.colors) }} steps: - name: Retrieve Artifact uses: actions/download-artifact@v4 with: name: ${{ matrix.color }} - name: Report Color run: | cat color
name: shared matrix
on:
push:
workflow_dispatch:
jobs:
define-matrix:
runs-on: ubuntu-latest
outputs:
colors: ${{ steps.colors.outputs.colors }}
steps:
- name: Define Colors
id: colors
run: |
echo 'colors=["red", "green", "blue"]' >> "$GITHUB_OUTPUT"
produce-artifacts:
runs-on: ubuntu-latest
needs: define-matrix
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Define Color
env:
color: ${{ matrix.color }}
run: |
echo "$color" > color
- name: Produce Artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.color }}
path: color
consume-artifacts:
runs-on: ubuntu-latest
needs:
- define-matrix
- produce-artifacts
strategy:
matrix:
color: ${{ fromJSON(needs.define-matrix.outputs.colors) }}
steps:
- name: Retrieve Artifact
uses: actions/download-artifact@v4
with:
name: ${{ matrix.color }}
- name: Report Color
run: |
cat color
处理故障
若要控制作业失败的处理方式,请使用 jobs.<job_id>.strategy.fail-fast
和 jobs.<job_id>.continue-on-error
。
可以同时使用 jobs.<job_id>.strategy.fail-fast
和 jobs.<job_id>.continue-on-error
。 例如,以下工作流将启动四个作业。 对于每个作业,continue-on-error
都由 matrix.experimental
的值确定。 如果任何具有 continue-on-error: false
的作业失败,所有正在进行或加入队列的作业都将被取消。 如果具有 continue-on-error: true
的作业失败,则其他作业将不会受到影响。
jobs:
test:
runs-on: ubuntu-latest
continue-on-error: ${{ matrix.experimental }}
strategy:
fail-fast: true
matrix:
version: [6, 7, 8]
experimental: [false]
include:
- version: 9
experimental: true
有关参考信息,请参阅 jobs.<job_id>.strategy.fail-fast
和 jobs.<job_id>.continue-on-error
。
定义最大并发作业数
若要设置使用 matrix
作业策略时可以同时运行的最大作业数,请使用 jobs.<job_id>.strategy.max-parallel
。
例如,以下工作流一次最多运行两个作业,即使运行器可同时运行六个作业。
jobs:
example_matrix:
strategy:
max-parallel: 2
matrix:
version: [10, 12, 14]
os: [ubuntu-latest, windows-latest]
有关参考信息,请参阅 GitHub Actions 的工作流语法。