How to Run a Matrix Build in Azure Pipelines

By Kaveh Alemi·Latchkey

Azure Pipelines fans a job across combinations with strategy: matrix, each exposing its values as variables.

Define named matrix legs under strategy: matrix. Each leg becomes a parallel job copy; the leg's key/value pairs are available as variables.

Matrix across Node versions

Each named leg sets variables consumed by the steps; maxParallel caps concurrency.

jobs:
  - job: test
    strategy:
      maxParallel: 3
      matrix:
        node18:
          NODE_VERSION: '18.x'
        node20:
          NODE_VERSION: '20.x'
        node22:
          NODE_VERSION: '22.x'
    pool: { vmImage: 'ubuntu-latest' }
    steps:
      - task: NodeTool@0
        inputs: { versionSpec: $(NODE_VERSION) }
      - script: npm ci && npm test

Gotchas

• Each matrix leg is named; that name shows in the run and must be unique within the job.
• maxParallel limits concurrent legs - useful to stay within your parallel-job license.
• For test slicing (not version fan-out), set parallel: N on the job and use System.JobPositionInPhase/System.TotalJobsInPhase.

Verify it actually works

• Trigger the real event rather than a manual run. Manual dispatch populates a different context, so behaviour depending on the event will differ.
• Assert on the outcome, not on the step exiting zero. Many steps report success while producing nothing.
• Check it on a fresh runner with a cold cache once, so you are not testing warm state that will not exist on the next contributor machine.

Frequently asked questions

Related guides

References

• GitHub Actions documentation