Parallel stages and matrix builds

Key points

• A parallel block runs its child stages at the same time, each holding one executor for its whole run.
• failFast true kills the surviving branches the moment the first branch fails.
• A matrix expands its axes into one cell per combination, so 3 by 3 axes means 9 builds of the same code.
• Cells run in parallel, so one careless matrix can occupy the whole agent pool and queue every other job.
• Use excludes to drop combinations that make no sense rather than guarding inside the stage.
• Parallel branches share no workspace, so a file written in one branch is invisible to another unless you stash it.

Example

stage('Cross-check') {
  matrix {
    axes {
      axis { name 'JDK';      values '17', '21' }
      axis { name 'PLATFORM'; values 'linux', 'windows' }
    }
    excludes {
      exclude {
        axis { name 'PLATFORM'; values 'windows' }
        axis { name 'JDK';      values '17' }
      }
    }
    agent { label "${PLATFORM}" }
    stages {
      stage('Test') {
        // sh does not exist on a Windows agent, and ./gradlew is not its launcher.
        // A matrix that spans operating systems has to branch on the platform.
        steps {
          script {
            if (isUnix()) { sh  "./gradlew --no-daemon test -PjdkVersion=${JDK}" }
            else          { bat "gradlew.bat --no-daemon test -PjdkVersion=${JDK}" }
          }
        }
      }
    }
  }
}

Parallel costs one executor per branch and matrix multiplies axes, so exclude the cells nobody ships.