Skip to main content

对作业使用矩阵

创建矩阵以定义每个作业的变体。

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

关于矩阵策略

A matrix strategy lets you use variables in a single job definition to automatically create multiple job runs that are based on the combinations of the variables. 例如,可以使用矩阵策略在一种语言的多个版本或多个操作系统上测试代码。

使用矩阵策略

使用 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]

将为每个可能的变量组合运行一个作业。 在此示例中,工作流程将运行六个作业,每个作业对应于 osversion 变量的组合。

默认情况下,GitHub Enterprise Server 将根据运行器的可用性最大化并行运行的作业数。 矩阵中变量的顺序决定了作业的创建顺序。 您定义的第一个变量将是工作流程运行中创建的第一个作业。 例如,上面的矩阵将按以下顺序创建作业:

  • {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}

矩阵将为每个工作流运行生成最多 256 个作业。 此限制适用于 GitHub Enterprise Server 托管和自托管运行器。

您定义的变量将成为 matrix 上下文中的属性,您可以在工作流程文件的其他区域中引用该属性。 在此示例中,可以使用 matrix.versionmatrix.os 来访问作业所用 versionos 的当前值。 更多信息请参阅“上下文”。

示例:使用单维矩阵

可以指定单个变量来创建单维矩阵。

例如,以下工作流程使用值 [10, 12, 14] 定义变量 version。 工作流程将运行三个作业,变量中的每个值对应一个作业。 每个作业将通过 matrix.version 上下文访问 version 值,并将该值作为 node-version 传递给 actions/setup-node 操作。

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.version }}

示例:使用多维矩阵

您可以指定多个变量来创建多维矩阵。 将为每个可能的变量组合运行一个作业。

例如,以下工作流程指定了两个变量:

  • os 变量中指定的两个操作系统
  • version 变量中指定的三个 Node.js 版本

工作流程将运行六个作业,每个作业对应于 osversion 变量的组合。 每个作业都会将 runs-on 值设置为当前 os 值,并将当前 version 值传递给 actions/setup-node 操作。

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

示例:使用上下文创建矩阵

您可以使用上下文来创建矩阵。 有关上下文的更多信息,请参阅“上下文”。

例如,以下工作流程在发生 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@v3
        with:
          node-version: ${{ matrix.version }}

扩展或添加矩阵配置

使用 jobs.<job_id>.strategy.matrix.include 扩展现有矩阵配置或添加新配置。 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}

遵循以下逻辑:

  • {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} 矩阵组合中,因为该组合不是原始矩阵组合之一。

示例:展开配置

例如,以下工作流程将运行六个作业,每个作业对应于 osnode 的组合。 当 windows-latest 值为 os16 值为 node 的作业运行时,作业中将包含一个名为 npm、值为 6 的附加变量。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

示例:添加配置

例如,此矩阵将运行 10 个作业,矩阵中 osversion 的每个组合各一个作业,再加上一个 windows-latest 值为 os17 值为 version 的作业。

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

如果未指定任何矩阵变量,则 include 下的所有配置都将运行。 例如,以下工作流程将运行两个作业,每个作业一个 include 条目。 这使您可以利用矩阵策略,而无需完全填充的矩阵。

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

排除矩阵配置

若要删除矩阵中定义的特定配置,请使用 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 }}

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

失败处理

您可以使用 jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-error 控制如何处理作业失败。

jobs.<job_id>.strategy.fail-fast 适用于整个矩阵。 如果jobs.<job_id>.strategy.fail-fast 设置为 true,如果矩阵中的任何作业失败, GitHub Enterprise Server 将取消矩阵中所有正在进行的作业和排队的作业。 此属性默认为 true

jobs.<job_id>.continue-on-error 适用于单个作业。 如果 jobs.<job_id>.continue-on-errortrue,则矩阵中的其他作业将继续运行,即使具有 jobs.<job_id>.continue-on-error: true 的作业失败也一样。

您可以同时使用 jobs.<job_id>.strategy.fail-fastjobs.<job_id>.continue-on-error。 例如,以下工作流程将启动四个作业。 对于每个作业,continue-on-errormatrix.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

定义并发作业的最大数量

默认情况下,GitHub Enterprise Server 将根据运行器的可用性最大化并行运行的作业数。 要设置在使用 matrix 作业策略时可以同时运行的最大作业数,请使用 jobs.<job_id>.strategy.max-parallel

例如,以下工作流程一次最多运行两个作业,即使有运行器可以同时运行所有六个作业也是如此。

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]