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 determined.
• The Runner tags can cover the required runtime 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

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

include is used to append specific combinations to the 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 in 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 other unfinished job instances are canceled immediately.
• fail-fast: false: If any job instance fails, the remaining job instances continue to run.

Note: strategy.fail-fast and stages.fail_fast are control at 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 matrix job instances that can run simultaneously. If not set, the default maximum parallelism depends on the number of available Runners.

runs-on Dynamic Selection

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]