How to use the Matrix strategy in Azure DevOps pipelines

The matrix strategy in Azure DevOps pipelines allows you to run the same job multiple times using different variable-sets. Instead of creating separate jobs for each variable, you define a single job and a matrix of configurations, and the pipeline automatically creates one job for every combination.

Why use the matrix strategy?

The matrix keyword is useful when you need to:

• Test your code across multiple operating systems (e.g. Windows, Linux)
• Ensure your code runs on different runtimes (e.g. Node or Python versions)
• Build your application with different configurations (e.g. Debug, Release)
• Run parallel jobs with different configurations without duplicating pipeline code

Basic syntax

In its simplest form, the matrix defines a mapping where each key represents a unique job instance.

strategy:
  matrix:
    jobNameA: # key
      variable1: value1
      variable2: value2
    jobNameB: # key
      variable1: value3
      variable2: value4

• The strategy keyword should indent the matrix one
• Each entry underneath the matrix keyword creates a separate job
• You can reference the variables within that job using $(variableName), for example $(variable1)
• You can control parallelism with maxParallel parameter

Example: Testing multiple node.js versions

jobs:
  - job: Test
    strategy:
      matrix:
        Node20:
          nodeVersion: '20.x'
        Node22:
          nodeVersion: '22.x'
        Node24:
          nodeVersion: '24.x'
      maxParallel: 3
    steps:
      - task: UseNode@1
        inputs:
          version: $(nodeVersion)
      - script: |
          npm install
          npm test
        displayName: 'Install and Test'

This snippet will create three parallel jobs, without duplicating the job definition.

Multi-variable matrix

You can combine multiple variables to create more complex matrices:

jobs:
  - job: Build
    displayName: "Build on $(vmImage) - $(buildConfig)"
    pool:
      vmImage: $(vmImage) # will be expanded at runtime, when each matrix-job starts
    strategy:
      matrix:
        WindowsDebug:
          vmImage: windows-latest
          buildConfig: Debug
        WindowsRelease:
          vmImage: windows-latest
          buildConfig: Release
        LinuxDebug:
          vmImage: ubuntu-latest
          buildConfig: Debug
        LinuxRelease:
          vmImage: ubuntu-latest
          buildConfig: Release
    steps:
      - script: echo Building on $(vmImage) with configuration $(buildConfig)
      - task: DotNetCoreCLI@2
        inputs:
          command: build
          arguments: --configuration $(buildConfig)

This creates four jobs with different images and build configuration combinations.

Dynamic matrix with pipeline parameters

You can even create a dynamic matrix using parameters, which is useful when you want to let users select which versions to test at queue time.

parameters:
  - name: environments
    type: object
    default: ['Development', 'Staging', 'Production']

jobs:
  - job: Deploy
    strategy:
      matrix:
        $:
          $:
            targetEnv: $
    steps:
      - script: echo "Deploying to $(targetEnv)"

This approach is often more reliable than trying to dynamically construct a matrix, because parameters expand during template parsing.

Usage of matrix on other platforms

When switching platforms, GitHub Actions uses a nearly identical strategy: matrix to generate job permutations automatically, while GitLab CI achieves the same efficiency using the parallel: matrix keyword.