Matrix builds for multi-platform in Jenkins - Mini Project: Build & Apply

Matrix builds for multi-platform

📖 Scenario: You are working in a software team that needs to build and test an application on multiple operating systems. To save time, you want Jenkins to run builds on Windows, Linux, and macOS automatically in parallel.

🎯 Goal: Create a Jenkins pipeline using a matrix build to run the same build steps on three platforms: windows, linux, and mac.

📋 What You'll Learn

Create a Jenkins pipeline with a matrix block

Define an axis called os with values windows, linux, and mac

Inside the matrix, run a simple shell or batch command to print the current OS

Print the build result for each platform

💡 Why This Matters

🌍 Real World

Matrix builds help teams test software on many platforms automatically, saving time and catching platform-specific bugs early.

💼 Career

Understanding matrix builds is important for DevOps engineers and build managers to optimize CI/CD pipelines for multi-platform projects.

1

Create the Jenkins pipeline skeleton

Write a Jenkins pipeline script starting with pipeline { and agent any to allow builds on any available agent.

Jenkins

pipeline {
    agent any
    // Your code here
}

Hint

Start with pipeline { and specify agent any to run on any agent.

2

Add a matrix block with an axis for OS

Inside the pipeline, add a stages block with one stage named Build. Inside this stage, add a matrix block with an axis called os having values windows, linux, and mac.

Jenkins

pipeline {
    agent any
    stages {
        stage('Build') {
            matrix {
                axes {
                    // Your code here
                }
            }
        }
    }
}

Hint

Use matrix { axes { axis { name 'os' values 'windows', 'linux', 'mac' } } inside the Build stage.

3

Add build steps inside the matrix to print the OS

Inside the matrix block, add a stages block with a stage named Run. Inside this stage, add a steps block that runs a shell command echo Building on ${os} for Linux and macOS, and a batch command echo Building on %os% for Windows. Use when condition to run the correct command based on the os value.

Jenkins

pipeline {
    agent any
    stages {
        stage('Build') {
            matrix {
                axes {
                    axis {
                        name 'os'
                        values 'windows', 'linux', 'mac'
                    }
                }
                stages {
                    stage('Run') {
                        steps {
                            // Your code here
                        }
                    }
                }
            }
        }
    }
}

Hint

Use script block with if (os == 'windows') to run bat command, else run sh command.

4

Print the build result for each platform

Add a post block inside the matrix block to print Build finished on ${os} after the build steps complete.

Jenkins

pipeline {
    agent any
    stages {
        stage('Build') {
            matrix {
                axes {
                    axis {
                        name 'os'
                        values 'windows', 'linux', 'mac'
                    }
                }
                stages {
                    stage('Run') {
                        steps {
                            script {
                                if (os == 'windows') {
                                    bat 'echo Building on %os%'
                                } else {
                                    sh 'echo Building on ${os}'
                                }
                            }
                        }
                    }
                }
                post {
                    // Your code here
                }
            }
        }
    }
}

Hint

Use post { always { echo "Build finished on ${os}" } } inside the matrix block.

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