Configuration Matrix Construction

This document introduces how to achieve parallel builds and tests across multiple operating systems, language versions, and architectures using strategy.matrix.

When you need to execute tests or builds in parallel across multiple combinations of operating systems, language versions, and architectures.

Prerequisites

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

Quick Example

name: matrix-test

on:
  push:
    branches:
      - main

jobs:
  test:
    name: Test
    runs-on: ['${{ matrix.os }}','${{ matrix.arch }}',small]
    strategy:
      matrix:
        os: [ubuntu-latest, euler-latest]
        arch: [x64]
        node-version: [18, 20]
        exclude:
        - os: euler-latest
          node-version: 18
      fail-fast: false
      max-parallel: 4
    steps:
      - name: Checkout source code
        uses: checkout
      - name: setup node
        uses: setup-node
        with:
          node-version: ${{ matrix.node-version }}
      - name: Run ci
        run: npm ci
      - name
        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, euler-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, euler-latest]
    arch: [x64, arm64]
    node-version: [18, 20]

include Expansion and Additional Configuration

include is used to append specific combinations to the existing matrix or add additional variables for specific combinations:

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

Variables not defined in the base matrix within include will also 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, euler-latest]
    node-version: [18, 20]
    exclude:
      - os: euler-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 immediately canceled.
• fail-fast: false: If any job instance fails, the remaining job instances continue to execute.

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

max-parallel Maximum Parallelism

strategy:
  max-parallel: 4

Limits the number of matrix job instances that can run simultaneously. 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:
    name: Test
    runs-on: [${{ matrix.os }},${{ matrix.arch }},small]
    strategy:
      matrix:
        os: [ubuntu-latest, euler-latest]
        arch: [x64, arm64]