在工作流中运行作业的变体

关于矩阵策略

使用矩阵策略，可以在单个作业定义中使用变量自动创建基于变量组合的多个作业运行。例如，可以使用矩阵策略在某个语言的多个版本或多个操作系统上测试代码。

向工作流程作业添加矩阵策略

使用 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 的工作流语法

使用输出定义两个矩阵

可使用一个作业的输出来定义多个作业的矩阵。

例如，以下工作流演示了如何在一个作业中定义值的矩阵，在第二个作业中使用该矩阵生成项目，然后在第三个作业中使用这些项目。每个项目都与矩阵中的值相关联。

YAML

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 的工作流语法。

在工作流中运行作业的变体

本文内容