How to Build a Multi-Dimension Matrix in GitHub Actions

Two matrix dimensions produce the cross-product: every OS paired with every version becomes its own job.

List more than one key under strategy.matrix. GitHub multiplies the dimensions, so three OSes times three versions equals nine parallel jobs.

Steps

• Declare each dimension as its own key under matrix.
• Reference every dimension you need inside the job.
• Count the product before you commit; it is the number of jobs.

Workflow

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

Gotchas

• A matrix may not generate more than 256 jobs per run.
• Trim the cross-product with exclude when some pairs are not worth running.

Related guides