How to Run a Matrix Across OS Agents in a Jenkins Pipeline

The Jenkins matrix directive fans a stage across OS agents by using an axis value as the agent label.

Define a PLATFORM axis whose values are agent labels, set the inner agent { label "${PLATFORM}" }, and the matrix runs the stages on each OS in parallel.

Matrix with a platform axis

Each axis value is an agent label; the matrix runs the inner stages on each OS node concurrently.

pipeline {
  agent none
  stages {
    stage('Cross-platform test') {
      matrix {
        axes {
          axis { name 'PLATFORM'; values 'linux', 'windows', 'mac' }
        }
        agent { label "${PLATFORM}" }
        stages {
          stage('Test') {
            steps { sh 'npm ci && npm test' }
          }
        }
      }
    }
  }
}

Gotchas

• Each axis value must correspond to a real agent label, or that combination waits forever for a node.
• Windows agents run bat, not sh - branch on PLATFORM for platform-specific steps.
• Use excludes inside matrix to drop combinations you do not want to run.

Related guides