跳到主要内容

Configuration Matrix Construction

Applicable Scenario: When you need to run tests or builds in parallel across multiple operating systems, multiple language versions, and various architecture combinations.

Prerequisites​

  • The dimensions to be tested (OS, language version, architecture, etc.) have been identified.
  • It has been confirmed that the Runner tags can cover the required runtime environments.

Quick Example​

name: matrix-test

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ${{ matrix.os }},${{ matrix.arch }},small
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        arch: [x64]
        node-version: [18, 20]
      exclude:
        - os: windows-latest
          node-version: 18
      fail-fast: false
      max-parallel: 4
    steps:
      - uses: checkout
      - uses: setup-node
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

Configuration Explanation​

Definition of Matrix Variables​

matrix defines matrix variables, and each combination of variable values generates a job instance:

One-dimensional matrix:

strategy:
  matrix:
    node-version: [18, 20, 22]

Two-dimensional matrix:

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18, 20]

The above two-dimensional matrix will generate 2 × 2 = 4 job instances.

Three-dimensional matrix:

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    arch: [x64, arm64]
    node-version: [18, 20]

include Expansion and Append Configuration​

include is used to append specific combinations or add additional variables to specific combinations:

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18, 20]
    include:
      - os: macos-latest
        node-version: 20
        experimental: true

Variables not defined in the base matrix in include (such as experimental) will be added to the corresponding job instance.

exclude Exclude Specific Combinations​

exclude is used to exclude specific combinations from the matrix:

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node-version: [18, 20]
    exclude:
      - os: windows-latest
        node-version: 18

After exclusion, 3 job instances are actually generated (instead of 4).

fail-fast Fast Failure Strategy​

strategy:
  fail-fast: true
  • fail-fast: true: If any job instance fails, all remaining unfinished job instances are canceled immediately.
  • fail-fast: false: If any job instance fails, the remaining job instances continue to execute.

Note: strategy.fail-fast and stages.fail_fast are different levels of control. strategy.fail-fast controls the behavior of job instances within the matrix, while stages.fail_fast controls the behavior between stages.

max-parallel Maximum Parallelism​

strategy:
  max-parallel: 4

Limits the number of matrix job instances running at the same time. If not set, the default maximum parallelism depends on the number of available Runners.

Dynamic Selection of runs-on​

In the matrix, runs-on can dynamically select the Runner by referencing matrix variables:

jobs:
  test:
    runs-on: ${{ matrix.os }},${{ matrix.arch }},small
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        arch: [x64, arm64]