Matrix configuration with Jenkins pipelines

Question

The Jenkins Pipeline plugin (aka Workflow) can be extended with other Multibranch plugins to build branches and pull requests automatically.

What would be the preferred way to run multiple configurations? For example, building with Java 7 and Java 8. This is often called matrix configuration (because of the multiple combinations such as language version, framework version, ...) or build variants.

I tried:

• executing them serially as separate stage steps. Good, but takes more time than necessary.
• executing them inside a parallel step, with or without nodes allocated inside them. Works but I cannot use the stage step inside parallel for known limitations on how it would be visualized.

Is there a recommended way to do this?

Answer 1

TLDR: Jenkins.io wants you to use nodes for each build.

Jenkins.io: In pipeline coding contexts, a "node" is a step that does two things, typically by enlisting help from available executors on agents:

1. Schedules the steps contained within it to run by adding them to the Jenkins build queue (so that as soon as an executor slot is free on a node, the appropriate steps run)

2. It is a best practice to do all material work, such as building or running shell scripts, within nodes, because node blocks in a stage tell Jenkins that the steps within them are resource-intensive enough to be scheduled, request help from the agent pool, and lock a workspace only as long as they need it.

Vanilla Jenkins Node blocks within a stage would look like:

stage 'build' {     node('java7-build'){ ... }     node('java8-build'){ ... } } 

Further extending this notion Cloudbees writes about parallelism and distributed builds with Jenkins. Cloudbees workflow for you might look like:

stage 'build' {     parallel 'java7-build':{       node('mvn-java7'){ ... }     }, 'java8-build':{       node('mvn-java8'){ ... }     } } 

Your requirements of visualizing the different builds in the pipeline would could be satisfied with either workflow, but I trust the Jenkins documentation for best practice.

---

EDIT

To address the visualization @Stephen would like to see, He's right - it doesn't work! The issue has been raised with Jenkins and is documented here, the resolution of involving the use of 'labelled blocks' is still in progress :-(

Q: Is there documentation letting pipeline users not to put stages inside of parallel steps?

A: No, and this is considered to be an incorrect usage if it is done; stages are only valid as top-level constructs in the pipeline, which is why the notion of labelled blocks as a separate construct has come to be ... And by that, I mean remove stages from parallel steps within my pipeline.

If you try to use a stage in a parallel job, you're going to have a bad time.

ERROR: The ‘stage’ step must not be used inside a ‘parallel’ block. 

Answer 2

I would suggest Declarative Matrix as a preferred way to run multiple configurations in Jenkins. It allows you to execute the defined stages for every configuration without code duplication.

Example:

pipeline {     agent none     stages {         stage('Test') {             matrix {                 agent {                     label "${NODENAME}"                 }                 axes {                     axis {                         name 'NODENAME'                         values 'java7node', 'java8node'                     }                 }                 stages {                     stage('Test') {                         steps {                             echo "Do Test for ${NODENAME}"                         }                     }                 }             }         }     } } 

Note that declarative Matrix is a native declarative Pipeline feature, so no additional Plugin installation needed.

Jenkins blog post about the matrix directive.