GitHub Actions Matrix Builds: Multi-OS & Multi-Version

GitHub Actions matrix Strategy lets you define a set of variables that generate multiple job variations, running your tests across every combination in parallel.

What You'll Learn

In this tutorial, you'll learn how to create matrix builds for multi-OS testing, multi-version testing, exclude specific combinations, add new variables dynamically, and organize matrix results.

Why It Matters

Code that works on your machine may fail on a different OS, Python version, or dependency set. Matrix builds catch these issues automatically by running the same tests across every combination you specify, without duplicating workflow code.

Real-World Use

Doda Browser tests its cross-platform file manager across Ubuntu 22.04, Windows Server 2022, and macOS 14, with Node.js versions 18, 20, and 22 -- nine combinations total. A failing combination is flagged before the Pull Request is merged.

Basic Matrix

Define a matrix with one variable:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

Multi-Variable Matrix

Combine OS and language versions:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -r requirements.txt
      - run: pytest

Excluding Combinations

Skip specific OS and version pairs:

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

Including Additional Values

Add specific combinations on top of the generated matrix:

strategy:
  matrix:
    os: [ubuntu-latest]
    node-version: [20]
    include:
      - os: ubuntu-latest
        node-version: 22
        experimental: true
      - os: windows-latest
        node-version: 20
        npm-version: 10

Matrix Job Names

Customize job display names:

jobs:
  test:
    name: Test on ${{ matrix.os }} with Node ${{ matrix.node-version }}

Practice Questions

1. What is a matrix Strategy in GitHub Actions? It generates multiple job variations based on defined variables, running the same steps for each combination.

2. How do you skip specific OS and version combinations? Use the exclude key under <a href="/design-patterns/strategy/">Strategy</a>.matrix with the values you want to exclude.

3. What does the include key do? It adds extra variable combinations or inserts additional variables for specific matrix entries.

4. How many jobs does a 3x3 matrix produce? Nine jobs, one for each combination of the two variables.

5. Challenge: Create a matrix with three operating systems and two Python versions. Exclude the Windows and Python 3.12 combination. Verify the workflow runs five jobs instead of six.

Mini Project: Cross-Platform Test Matrix

Build a matrix workflow for a Node.js CLI tool. Test across Ubuntu, Windows, and macOS with Node.js 18, 20, and 22. Add a job that runs only on the latest Ubuntu with Node.js 22 and runs additional integration tests. Upload test results as artifacts.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.