Matrix builds for multi-platform in Jenkins - Step-by-Step Execution

Process Flow - Matrix builds for multi-platform

Start Build

↓

Define Matrix Axes

↓

Generate Combinations

↓

Run Each Combination

↓

Collect Results

↓

Report Success/Failure

↓

End

The build starts by defining platforms and configurations, then runs all combinations in parallel, collects results, and reports the final status.

Execution Sample

Jenkins

pipeline {
  agent any
  stages {
    matrix {
      axes {
        axis {
          name 'PLATFORM'
          values 'linux', 'windows'
        }
      }
      stages {
        stage('Build') {
          steps {
            echo "Building on ${PLATFORM}"
          }
        }
      }
    }
  }
}

This Jenkins pipeline runs a build stage on both Linux and Windows platforms using a matrix.

Process Table

Step	Matrix Axis	Combination	Action	Output
1	PLATFORM	linux	Start build for linux	Echo: Building on linux
2	PLATFORM	windows	Start build for windows	Echo: Building on windows
3	All combinations	linux, windows	Collect results	Both builds completed successfully
4	Final	-	Report status	Build success if all passed

💡 All matrix combinations completed, build ends with aggregated result

Status Tracker

Variable	Start	After 1	After 2	Final
PLATFORM	-	linux	windows	-
Build Status	pending	success (linux)	success (windows)	success

Key Moments - 3 Insights

Why does Jenkins run multiple builds in parallel here?

Because the matrix defines multiple platforms (linux, windows), Jenkins runs each combination separately and in parallel as shown in execution_table rows 1 and 2.

How does Jenkins know when the entire matrix build is done?

Jenkins waits for all combinations to finish (rows 1 and 2), then collects results (row 3) before reporting final status (row 4).

What happens if one platform build fails?

The final report (row 4) will mark the overall build as failed, even if other platforms succeeded.

Visual Quiz - 3 Questions

Look at the execution table, what is the PLATFORM value at step 2?

A windows

B macOS

C linux

D android

💡 Hint

Check the 'Combination' column at step 2 in the execution_table.

At which step does Jenkins collect results from all builds?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look for the 'Collect results' action in the execution_table.

If a new platform 'macOS' is added to the matrix, what changes in the execution_table?

A Step 4 will be removed

B An extra row for macOS build will appear between steps 2 and 3

C Step 1 will run twice

D No changes needed

💡 Hint

Adding a platform adds a new combination build step before collecting results.

Concept Snapshot

Matrix builds run multiple configurations in parallel.
Define axes like PLATFORM with values (linux, windows).
Jenkins runs each combination as a separate build.
Results are collected and aggregated at the end.
Useful for testing multi-platform compatibility.

Full Transcript

Matrix builds in Jenkins allow running the same build on multiple platforms or configurations automatically. The process starts by defining axes such as PLATFORM with values like linux and windows. Jenkins generates all combinations and runs each build in parallel. After all builds finish, Jenkins collects the results and reports the overall status. This helps test software on different environments efficiently.

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