Running Workflows on Multiple OS and Node.js Versions with Matrix Strategy

Run Workflows on Multiple OS and Node.js Versions with GitHub Actions

Need to run your workflow on multiple operating systems and Node.js versions? You don’t have to duplicate jobs manually — you can use the matrix strategy in GitHub Actions.

With a matrix, you define combinations of values (like OS and Node version), and GitHub Actions automatically creates a job for each combination.

Example Scenario

Suppose we have a Node.js application and want to run unit tests on:

• Multiple operating systems
• Multiple Node.js versions

We define the matrix values as:

platform: [ubuntu-latest, macos-latest, windows-latest]
node-versions: ["16", "18", "22"]

GitHub Actions Workflow

Here’s how to use these values in your workflow:

name: Unit Testing

on:
  push:
    branches:
      - main
      - "feature/*"

jobs:
  unit-testing:
    name: Unit Testing
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node-version: [16, 18, 22]

    runs-on: ${{ matrix.os }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js ${{ matrix['node-version'] }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix['node-version'] }}

      - name: Install dependencies
        run: npm install

      - name: Run unit tests
        id: nodejs-unit-test
        run: npm test

Excluding Specific Combinations

If you want to skip certain combinations — for example, Node.js 18 on macos-latest — you can use exclude in your matrix:

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

This generates all combinations of os × node-version, except the one where os = macos-latest and node-version = 18.