Configuration Matrix Construction

This document introduces how to achieve parallel builds and tests for 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
        run: npm test

Configuration Explanation

Matrix Variable Definition

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 Appending Configuration

include is used to append specific combinations to an existing matrix or add additional variables to 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 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 control different levels. 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 simultaneously running matrix job instances. 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 a 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]