Matrix builds for multi-platform in Jenkins - Commands & Configuration

Introduction

Building software for different platforms can be slow and repetitive. Matrix builds let Jenkins run the same steps for many platforms automatically, saving time and avoiding mistakes.

When you want to test your app on Windows, Linux, and macOS without writing separate jobs.

When you need to build Docker images for multiple CPU architectures like amd64 and arm64.

When you want to run the same tests on different Java versions to ensure compatibility.

When you want to compile your code for different operating systems from one Jenkins job.

When you want to save time by running builds in parallel for multiple environments.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent none
  stages {
    stage('Build and Test') {
      matrix {
        axes {
          axis {
            name 'OS'
            values 'linux', 'windows', 'mac'
          }
          axis {
            name 'ARCH'
            values 'amd64', 'arm64'
          }
        }
        agent {
          label "${OS} && ${ARCH}"
        }
        stages {
          stage('Checkout') {
            steps {
              checkout scm
            }
          }
          stage('Build') {
            steps {
              echo "Building on ${OS} for ${ARCH}"
              sh 'make build'
            }
          }
          stage('Test') {
            steps {
              echo "Testing on ${OS} for ${ARCH}"
              sh 'make test'
            }
          }
        }
      }
    }
  }
}

This Jenkinsfile defines a pipeline with a matrix stage.

The axes section lists the platforms: OS (linux, windows, mac) and ARCH (amd64, arm64).

Jenkins runs all combinations in parallel, using agents labeled by OS and ARCH.

Inside each matrix cell, it checks out code, builds, and tests.

Commands

This command updates the Jenkins job configuration with the matrix build pipeline defined in the Jenkinsfile.

Terminal

jenkins-jobs --conf jenkins.ini update my-matrix-job

Expected Output

Job 'my-matrix-job' updated successfully

→

--conf - Specifies the Jenkins configuration file to connect to the server

This command triggers the matrix build job on Jenkins and waits for it to finish, showing the build status.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 build my-matrix-job -s

Expected Output

Started build #42

Finished: SUCCESS

→

-s - Waits for the build to complete and shows the result

This command fetches the console output of build number 42 to see logs from all matrix runs.

Terminal

java -jar jenkins-cli.jar -s http://localhost:8080 console my-matrix-job 42

Expected Output

[linux amd64] Building on linux for amd64

[linux amd64] Build successful

[windows arm64] Building on windows for arm64

[windows arm64] Build successful

[mac amd64] Building on mac for amd64

[mac amd64] Build successful

Finished: SUCCESS

Key Concept

Matrix builds let you run the same pipeline steps automatically across many platform combinations in parallel.

Common Mistakes

Not labeling Jenkins agents correctly for each OS and architecture.

Jenkins cannot find an agent to run the job for that platform, causing build failures.

Ensure agents have labels matching the matrix axes values, like 'linux' and 'amd64'.

Using 'agent any' inside the matrix instead of specifying labels.

The build may run on the wrong platform, invalidating the test results.

Use 'agent { label "${OS} && ${ARCH}" }' to run on the correct platform.

Not defining all axes needed for the platforms you want to test.

Some platform combinations won't run, missing important tests.

List all OS and architecture values explicitly in the matrix axes.

Summary

Define a Jenkins pipeline with a matrix stage listing OS and architecture axes.

Jenkins runs all combinations in parallel on agents labeled for each platform.

Use CLI commands to update the job, trigger builds, and view logs for all matrix runs.

Practice

1. What is the main purpose of using a matrix build in Jenkins for multi-platform projects?

easy

A. To run the same build steps on multiple platform combinations automatically

B. To run only one build on a single platform

C. To manually select which platform to build on

D. To speed up builds by skipping tests

Solution

1. Step 1: Understand matrix build concept

   A matrix build runs the same steps on different combinations of variables like OS and architecture.

2. Step 2: Identify the purpose for multi-platform

   This allows testing and building on all required platforms automatically without manual intervention.

3. Final Answer:

   To run the same build steps on multiple platform combinations automatically -> Option A

4. Quick Check:

   Matrix build = multi-platform automatic runs [OK]

Hint: Matrix builds run all platform combos automatically [OK]

Common Mistakes:

• Thinking matrix builds run only on one platform
• Confusing matrix with manual selection
• Assuming matrix skips tests

2. Which syntax correctly defines two axes named os and arch in a Jenkins matrix build?

easy

A. matrix { axis name='os' values='linux,windows'; axis name='arch' values='x86,arm' }

B. matrix { os: ['linux', 'windows'], arch: ['x86', 'arm'] }

C. axes { axis('os', ['linux', 'windows']); axis('arch', ['x86', 'arm']) }

D. axes { axis { name 'os'; values 'linux', 'windows' } axis { name 'arch'; values 'x86', 'arm' } }

Solution

1. Step 1: Recall Jenkins matrix axes syntax

   Jenkins uses axes { axis { name '...' ; values '...' } } blocks to define axes.

2. Step 2: Match syntax with options

   axes { axis { name 'os'; values 'linux', 'windows' } axis { name 'arch'; values 'x86', 'arm' } } matches the correct syntax with two axis blocks inside axes.

3. Final Answer:

   axes { axis { name 'os'; values 'linux', 'windows' } axis { name 'arch'; values 'x86', 'arm' } } -> Option D

4. Quick Check:

   Correct axis syntax = axes { axis { name 'os'; values 'linux', 'windows' } axis { name 'arch'; values 'x86', 'arm' } } [OK]

Hint: Use axes { axis { name; values } } for matrix axes [OK]

Common Mistakes:

• Using incorrect matrix or axis syntax
• Mixing JSON-like syntax instead of Groovy
• Missing semicolons or braces

3. Given this Jenkins matrix snippet:

axes {
  axis {
    name 'os'
    values 'linux', 'windows'
  }
  axis {
    name 'arch'
    values 'x86', 'arm'
  }
}
stages {
  stage('Build') {
    steps {
      echo "Building on ${os} for ${arch}"
    }
  }
}

How many total build combinations will Jenkins run?

medium

A. 6

B. 2

C. 4

D. 8

Solution

1. Step 1: Count values in each axis

   Axis 'os' has 2 values: linux, windows. Axis 'arch' has 2 values: x86, arm.

2. Step 2: Calculate total combinations

   Total combinations = 2 (os) * 2 (arch) = 4.

3. Final Answer:

   4 -> Option C

4. Quick Check:

   2 OS * 2 arch = 4 builds [OK]

Hint: Multiply axis values count for total combinations [OK]

Common Mistakes:

• Adding instead of multiplying axis values
• Counting only one axis
• Misreading axis values count

4. You wrote this matrix build snippet but Jenkins fails with an error:

axes {
  axis {
    name 'os'
    values 'linux', 'windows'
  }
  axis {
    name 'arch'
    value 'x86', 'arm'
  }
}

What is the error and how to fix it?

medium

A. Typo: use 'values' instead of 'value' in second axis

B. Missing quotes around 'x86' and 'arm'

C. Axes block should be named 'matrix' not 'axes'

D. Use commas instead of spaces between values

Solution

1. Step 1: Identify syntax error in axis definition

   The second axis uses 'value' instead of the correct 'values' keyword.

2. Step 2: Correct the keyword

   Change 'value' to 'values' to fix the syntax error and allow multiple values.

3. Final Answer:

   Typo: use 'values' instead of 'value' in second axis -> Option A

4. Quick Check:

   Axis keyword must be 'values' [OK]

Hint: Check for 'values' keyword spelling in axes [OK]

Common Mistakes:

• Using 'value' instead of 'values'
• Forgetting commas between values
• Misnaming axes block

5. You want to run a matrix build on OS (linux, windows) and arch (x86, arm), but only run the 'arm' builds on agents labeled 'arm-node'. How do you configure the matrix to achieve this?

hard

A. Set agent { label 'arm-node' } globally for all builds

B. Use agent { label "${arch == 'arm' ? 'arm-node' : ''}" } inside the matrix

C. Add when { expression { arch == 'arm' } } to skip arm builds

D. Use exclude { axis { name 'arch'; value 'arm' } } to remove arm builds

Solution

1. Step 1: Understand agent labeling per axis value

   You want 'arm' builds to run only on 'arm-node' labeled agents, others on default.

2. Step 2: Use conditional label assignment in agent block

   Using agent { label "${arch == 'arm' ? 'arm-node' : ''}" } assigns 'arm-node' label only for arm builds.

3. Final Answer:

   Use agent { label "${arch == 'arm' ? 'arm-node' : ''}" } inside the matrix -> Option B

4. Quick Check:

   Conditional agent label = Use agent { label "${arch == 'arm' ? 'arm-node' : ''}" } inside the matrix [OK]

Hint: Use conditional label in agent block for selective platforms [OK]

Common Mistakes:

• Setting global agent label affecting all builds
• Skipping arm builds instead of assigning correct agent
• Excluding arm builds instead of targeting agent