How to Use a Matrix Build in GitHub Actions

A matrix expands one job into many parallel jobs, one per combination of values.

Define strategy.matrix with one or more dimensions; the runner clones the job for each combination and exposes values via the matrix context.

Steps

• Add strategy.matrix with a list dimension (e.g. node).
• Reference ${{ matrix.node }} inside the job.
• Each combination runs as its own parallel job.

Workflow

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

Gotchas

• Total jobs are the product of all dimensions; large matrices burn minutes fast.
• Latchkey runs matrix jobs on cheaper managed runners and retries transient failures automatically.

Related guides