How to Use a Matrix Strategy in Azure Pipelines

A matrix expands one job into several named legs, each with its own variable values, running in parallel.

Under a job, set strategy.matrix to a map of named configurations. Each leg becomes a parallel job and exposes its matrix variables to steps.

Matrix across Node versions

Each leg sets nodeVersion; maxParallel caps concurrent legs.

jobs:
  - job: Test
    strategy:
      maxParallel: 2
      matrix:
        node18:
          nodeVersion: '18.x'
        node20:
          nodeVersion: '20.x'
    steps:
      - task: NodeTool@0
        inputs:
          versionSpec: $(nodeVersion)
      - script: npm ci && npm test

Gotchas

• Matrix leg names become part of the job identity - keep them stable to preserve history.
• Each leg runs on its own agent, so each must reinstall dependencies (cache them to save time).
• maxParallel limits agent consumption when your parallel-job quota is small.

Related guides