Using a build matrix for your jobs

注： GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。您可以在 GitHub 公共路线图上查看有关未来支持计划的更多信息。

概览

Use jobs.<job_id>.strategy to create a build matrix for your jobs. 您可以定义要在其中运行每项作业的不同变种。

Creating a matrix of different job configurations

Use jobs.<job_id>.strategy.matrix to define a matrix of different job configurations. 矩阵允许您通过在单个作业定义中执行变量替换来创建多个作业。例如，可以使用矩阵为多个受支持的编程语言、操作系统或工具版本创建作业。矩阵重新使用作业的配置，并为您配置的每个矩阵创建作业。

作业矩阵在每次工作流程运行时最多可生成 256 个作业。此限制也适用于自托管运行器。

您在 matrix 中定义的每个选项都有键和值。定义的键将成为 matrix 上下文中的属性，您可以在工作流程文件的其他区域中引用该属性。例如，如果定义包含操作系统数组的键 os，您可以使用 matrix.os 属性作为 runs-on 关键字的值，为每个操作系统创建一个作业。更多信息请参阅“上下文”。

定义 matrix 事项的顺序。定义的第一个选项将是工作流程中运行的第一个作业。

示例：运行多个版本的 Node.js

您可以提供配置选项阵列来指定矩阵。例如，如果运行器支持 Node.js 版本 10、12 和 14，则您可以在 matrix 中指定这些版本的阵列。

此示例通过设置三个 Node.js 版本阵列的 node 键创建三个作业的矩阵。为使用矩阵，示例将 matrix.node 上下文属性设置为 setup-node 操作的输入参数 node-version。 � 此，将有三个作业运行，每个使用不同的 Node.js 版本。

strategy:
  matrix:
    node: [10, 12, 14]
steps:
  # Configures the node version used on GitHub-hosted runners
  - uses: actions/setup-node@v2
    with:
      # The Node.js version to configure
      node-version: ${{ matrix.node }}

setup-node 操作是在使用 GitHub 托管的运行器时建议用于配置 Node.js 版本的方式。更多信息请参阅 setup-node 操作。

示例：使用多个操作系统运行

您可以创建矩阵以在多个运行器操作系统上运行工作流程。您也可以指定多个矩阵配置。此示例创建包含 6 个作业的矩阵：

在 os 阵列中指定了 2 个操作系统
在 node 阵列中指定了 3 个 Node.js 版本

定义操作系统矩阵时，必须将 runs-on 的值设置为您定义的 matrix.os 上下文属性。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [ubuntu-18.04, ubuntu-20.04]
    node: [10, 12, 14]
steps:
  - uses: actions/setup-node@v2
    with:
      node-version: ${{ matrix.node }}

要查找 GitHub 托管的运行器支持的配置选项，请参阅“GitHub 托管的运行器的虚拟环境”。

Example: Including additional values in combinations

您可以将额外的配置选项添� 到已经存在的构建矩阵作业中。例如，如果要在作业使用 windows-latest 和 node 的版本 8 运行时使用 npm 的特定版本，您可以使用 include 指定该附� 选项。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [8, 10, 12, 14]
    include:
      # includes a new variable of npm with a value of 6
      # for the matrix leg matching the os and version
      - os: windows-latest
        node: 8
        npm: 6

示例：包括新组合

您可以使用 include 将新作业添� 到构建矩阵中。任何不匹配包含配置都会添� 到矩阵中。例如，如果您想要使用 node 版本 14 在多个操作系统上构建，但在 Ubuntu 上需要一个使用节点版本 15 的额外实验性作业，则可使用 include 指定该额外作业。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    node: [14]
    os: [macos-latest, windows-latest, ubuntu-18.04]
    include:
      - node: 15
        os: ubuntu-18.04
        experimental: true

示例：从矩阵中排除配置

您可以使用 exclude 选项� 除构建矩阵中定义的特定配置。使用 exclude � 除由构建矩阵定义的作业。作业数量是您提供的数组中所包括的操作系统 (os) 数量减去所有减项 (exclude) 后的叉积。

runs-on: ${{ matrix.os }}
strategy:
  matrix:
    os: [macos-latest, windows-latest, ubuntu-18.04]
    node: [8, 10, 12, 14]
    exclude:
      # excludes node 8 on macOS
      - os: macos-latest
        node: 8

注意：所有 include 组合在 exclude 后处理。这允许您使用 include 添� 回以前排除的组合。

在矩阵中使用环境变量

您可以使用 include 键为每个测试组合添� 自定义环境变量。然后，您可以在后面的步骤中引用自定义环境变量。

在此示例中， node-version 的矩阵条目每个都被配置为对 site 和 datacenter 环境变量使用不同的值。 Echo site details 步骤然后使用 env: ${{ matrix.env }} 引用自定义变量：

name: Node.js CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
       include:
         - node-version: 10.x
           site: "prod"
           datacenter: "site-a"
         - node-version: 12.x
           site: "dev"
           datacenter: "site-b"
    steps:
      - name: Echo site details
        env:
          SITE: ${{ matrix.site }}
          DATACENTER: ${{ matrix.datacenter }}
        run: echo $SITE $DATACENTER

Canceling remaining jobs if a `matrix` job fails

When jobs.<job_id>.strategy.fail-fast is set to true, GitHub cancels all in-progress jobs if any matrix job fails. 默认值：true

Defining the maximum number of concurrent jobs in a `matrix`

Use jobs.<job_id>.strategy.max-parallel to set the maximum number of jobs that can run simultaneously when using a matrix job strategy. 默认情况下，GitHub 将最大化并发运行的作业数量，具体取决于 GitHub 托管虚拟机上可用的运行程序。

strategy:
  max-parallel: 2