Run the same set of stages for every combination of axis values. Useful for building multiple platforms, configurations, or any other multi-dimensional pipeline.

stages {
    perforce.sync()
    matrix(UE5_BUILD_PLATFORM: ['Win64', 'PS4'],
           UE5_BUILD_CONFIG: ['Development', 'Shipping']) {
        ue5.build()
        steam.deploy()
    }
    discord.alert()
}

This produces 4 combinations: Win64/Development, Win64/Shipping, PS4/Development, PS4/Shipping.

Stages outside the matrix (perforce.sync(), discord.alert()) run once. Stages inside the matrix repeat for each combination.

1. The matrix() block captures all modules registered inside its closure
2. It computes the cartesian product of all axis values
3. During execution, the orchestrator runs each combination sequentially
4. Each combination gets:
   • Overridden parameters — axis values are merged into the build parameters (e.g., params.UE5_BUILD_PLATFORM becomes 'Win64' for the first combination)
   • Isolated context — each combination gets its own ctx map so ctx.buildPlatform, ctx.buildConfig, etc. don't leak between combinations
   • Separate output directory — ${WORKSPACE}\Output\<value1>\<value2>\... (e.g., Output\Win64\Shipping)

Axis values can be a list or a single string:

// Multiple values — creates combinations
matrix(UE5_BUILD_PLATFORM: ['Win64', 'PS4', 'Linux']) { ... }

// Single value (string) — automatically wrapped in a list
matrix(UE5_BUILD_PLATFORM: 'Win64', UE5_BUILD_CONFIG: ['Development', 'Shipping']) { ... }

There is no limit on the number of axes, but keep in mind that combinations grow multiplicatively:

Combinations run sequentially on the same node, so more combinations = longer builds.

Axis names should match the parameter names of the modules inside the matrix. For example, UE5_BUILD_PLATFORM matches the UE5_BUILD_PLATFORM parameter from ue5.build(). The matrix overrides these parameters per combination at execution time.

Axis-controlled parameters remain visible in the Jenkins "Build with Parameters" UI. Their values are still overridden by the matrix for each combination.

The stage tree in Jenkins Blue Ocean or Stage View looks like:

P4 Sync
Matrix
├── Win64 / Development
│   ├── UE5 Build
│   └── Deploy > Steam Deploy
├── Win64 / Shipping
│   ├── UE5 Build
│   └── Deploy > Steam Deploy
├── PS4 / Development
│   └── ...
└── PS4 / Shipping
    └── ...
Discord Alert

Use only() inside a matrix to run specific stages for only certain combinations:

stages {
    perforce.sync()
    matrix(UE5_BUILD_PLATFORM: ['Win64', 'PS4'],
           UE5_BUILD_CONFIG: ['Development', 'Shipping']) {
        ue5.build()
        only(UE5_BUILD_PLATFORM: 'Win64', UE5_BUILD_CONFIG: 'Shipping') {
            steam.deploy()
            gdrive.deploy()
        }
    }
    discord.alert()
}

In this example, all 4 combinations are built, but only the Win64/Shipping combination deploys to Steam and Google Drive.

Condition values can be a list to match any of the given values:

// Deploy for both Win64 and Linux, but only Shipping
only(UE5_BUILD_PLATFORM: ['Win64', 'Linux'], UE5_BUILD_CONFIG: 'Shipping') {
    steam.deploy()
}

When a combination doesn't match the only() condition, the stages inside it are skipped entirely — they don't appear in the Jenkins Stage View for that combination.

• Only one matrix() block per pipeline is supported
• Combinations run sequentially on the same node (parallel execution across nodes is not yet supported)
• The VCS stage should be placed outside the matrix (it only needs to sync once)

@Library('JenkinsLib') _

stages {
    perforce.sync()
    matrix(UE5_BUILD_PLATFORM: ['Win64', 'PS4'],
           UE5_BUILD_CONFIG: ['Development', 'Shipping']) {
        ue5.build()
        ue5.test()
        only(UE5_BUILD_CONFIG: 'Shipping') {
            steam.deploy()
            gdrive.deploy()
        }
        only(UE5_BUILD_PLATFORM: 'Win64', UE5_BUILD_CONFIG: 'Development') {
            itch.deploy()
        }
    }
    discord.alert()
}

This pipeline:

1. Syncs from Perforce once
2. Builds and tests all 4 combinations
3. Deploys to Steam and GDrive only for Shipping builds (both platforms)
4. Deploys to itch.io only for Win64/Development
5. Sends a Discord notification after everything completes