Matrix Strategy for Multi-Version Testing

Matrix Testing Strategy

Matrix strategy is one of GitHub Actions' most powerful features. It lets you run the same job across multiple configurations — different language versions, operating systems, or any custom variable — without duplicating workflow code.

Workflow YAML

name: Matrix CI

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [18, 20, 22]
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

How Matrix Strategy Works

This configuration creates 9 jobs (3 OS x 3 Node versions). Each combination runs as a separate job in parallel, subject to your plan's concurrency limits.

Key Options

Option	Description
fail-fast: false	Continue running other matrix jobs even if one fails
fail-fast: true (default)	Cancel all matrix jobs when one fails
include	Add specific combinations not in the cross-product
exclude	Remove specific combinations from the cross-product
max-parallel	Limit the number of concurrent matrix jobs

Advanced: Include and Exclude

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

The include block adds an Ubuntu + Node 22 job with an extra experimental variable. The exclude block removes the Windows + Node 18 combination.

Referencing Matrix Variables

Use ${{ matrix.variable-name }} anywhere in job configuration — step inputs, environment variables, run commands, or conditional expressions.