Contributors
Plugin
Apache Maven in or bat "mvn ....
The selected maven installation is configured and prepended to the path.
It provides several Features to simplify the creation of your Pipeline scripts and ensure the Traceability of Maven builds .
It uses some Sensible default Maven parameters for a CI usage (batch-mode, ...) and automatically configures the Jenkins Report Publishers (Artifacts, JUnit, ...).
The Default Configuration can be defined globally or at the folder level to keep your pipeline code as short as possible while using the expected configuration (Maven settings.xml file...) globally or locally.
This plugin allows transitioning smoothly from the legacy Maven Settings Support and by proposing the Trigger downstream pipeline when a snapshot is built .
Please note per default some features will not be available and you will have to change/configure a database storage which suits your environment.
The plugin can be found under the name Pipeline Maven Integration Plugin in the Experimental Plugin Site and development versions (incremental releases) are archived on every successful build on
Release notes are recorded in Usage
The Pipeline Maven Plugin works with Linux, Windows and MacOSX build agents.
pipeline { agent any stages { stage("Build") { steps { git url: 'https://github.com/cyrille-leclerc/multi-module-maven-project' withMaven { sh "mvn clean verify" } // withMaven will discover the generated Maven artifacts, JUnit Surefire & FailSafe reports and FindBugs reports } } } }
It can supports various parameters to fine-tune its behavior.
Within a node or a docker.image block, create a withMaven block to set up a with maven environment.
The configured environment will be used when calling maven inside the block by using sh mvn or bat mvn.
The following parameters can be used to configure Maven:
Maven (maven): Allow the selection of a Maven installation configured on the Global Jenkins configuration or on the Global Tool Configuration page if using Jenkins > 2.0. When auto-install is enabled, maven will be downloaded and made available for the pipeline job.
JDK (jdk): Allows the selection of a JDK installation.
If auto-install is enabled, the JDK will be downloaded and made available for the pipeline job.
Maven Settings
Maven Settings Config (mavenSettingsConfig): Select a
Maven settings file ID from Config File Provider Plugin.
The settings' element in the settings.xml file contains elements used to define values which configure Maven execution in various ways, like the pom.xml, but should not be bundled to any specific project, or distributed to an audience. See also Config File Provider Plugin.
Maven Global Settings File Path (globalMavenSettingsFilePath): Specify the path to a Maven global settings.xml file on the build agent. The specified path can be absolute or relative to the workspace.
If none of globalMavenSettingsConfig and`globalMavenSettingsFilePath` are defined, withMaven(){} will use the Maven global settings defined in the Jenkins Global Tool Configuration if declared
Maven JVM Opts (mavenOpts): Specify JVM specific options needed when launching Maven as an external process, these are not maven specific options.
See:
mavenSettingsConfig and globalMavenSettingsConfig use the ID, not the name, of the Maven settings file (resp Maven Global Settings file).
pipeline { agent any stages { stage("Build") { steps { git url: 'https://github.com/cyrille-leclerc/multi-module-maven-project' withMaven( // Maven installation declared in the Jenkins "Global Tool Configuration" maven: 'maven-3', // (1) // Use `$WORKSPACE/.repository` for local repository folder to avoid shared repositories mavenLocalRepo: '.repository', // (2) // Maven settings.xml file defined with the Jenkins Config File Provider Plugin // We recommend to define Maven settings.xml globally at the folder level using // navigating to the folder configuration in the section "Pipeline Maven Configuration / Override global Maven configuration" // or globally to the entire master navigating to "Manage Jenkins / Global Tools Configuration" mavenSettingsConfig: 'my-maven-settings' // (3) ) { // Run the maven build sh "mvn clean verify" } // withMaven will discover the generated Maven artifacts, JUnit Surefire & FailSafe & FindBugs & SpotBugs reports... } } } }
In the above example the following parameters are used to configure Maven:
maven: 'maven-3' Maven Installation will be used, this installation has to be declared in the Global Jenkins configuration or Tool installations page.
mavenLocalRepo: a local repository folder is specified to avoid shared repositories
mavenSettingsConfig: specifies a specific settings.xml configuration from Features
The Maven parameters that are useful on a build server, --batch-mode (-B) and --no-transfer-progress (-ntp) are enable by default, no need to add them in your mvn invocations.
if Traceability of Maven builds is enabled, --no-transfer-progress (-ntp) option is removed, and --show-version (-V) is added.
global tools configuration maven settings default maven settings defined at the folder level
By setting the parameter traceability to true (either globally on the tools configuration page, or for one step in particular), the withMaven() pipeline step will capture in the logs of the build all the details of the execution:
global tools configuration traceability
Version of the JVM
withMaven(){} step initialization:
[withMaven] use JDK installation JDK8
mvn executable invocation:
Java version: 1.8.0_102, vendor: Oracle Corporation
Version of Maven
withMaven(){} step initialization:
[withMaven] use Maven installation 'M3'
mvn executable invocation:
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015年11月10日T16:41:47+00:00)
Name or path of the Maven settings.xml and Maven global settings.xml file.
withMaven(){} step initialization:
[withMaven] use Maven settings provided by the Jenkins Managed Configuration File 'maven-settings-for-supply-chain-build-job'
When using the Maven settings.xml and global settings.xml files provided by the pipeline { agent any stages { stage("Build") { steps { withMaven(traceability: true){ ..... } } } } }
node { stage ('Build') { withMaven(traceability: true) { ... } } }
[withMaven] use JDK installation JDK8 [withMaven] use Maven installation 'M3' [withMaven] use Maven settings provided by the Jenkins Managed Configuration File 'maven-settings-for-supply-chain-build-job' [withMaven] use Maven settings.xml 'maven-settings-for-supply-chain-build-job' with Maven servers credentials provided by Jenkins (replaceAll: true): [mavenServerId: 'nexus.beescloud.com', jenkinsCredentials: 'beescloud-nexus-deployment-credentials', username: 'deployment', type: 'UsernamePasswordCredentialsImpl'], [mavenServerId: 'github.beescloud.com', jenkinsCredentials: 'github-enterprise-api-token', username: 'dev1', type: 'UsernamePasswordCredentialsImpl'] ... Running shell script + mvn clean deploy ----- withMaven Wrapper script ----- Picked up JAVA_TOOL_OPTIONS: -Dmaven.ext.class.path=".../pipeline-maven-spy.jar" -Dorg.jenkinsci.plugins.pipeline.maven.reportsFolder="..." Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015年11月10日T16:41:47+00:00) Maven home: /home/ubuntu/jenkins-home/tools/hudson.tasks.Maven_MavenInstallation/M3 Java version: 1.8.0_102, vendor: Oracle Corporation Java home: /home/ubuntu/jenkins-home/tools/hudson.model.JDK/JDK8/jre Default locale: en_US, platform encoding: UTF-8 OS name: "linux", version: "3.13.0-109-generic", arch: "amd64", family: "unix"
Maven build executions inside the withMaven(){} will be detected and Jenkins will transparently
Archive and fingerprint generated Maven artifacts and Maven attached artifacts
Publish JUnit / Surefire reports (if the
Publish Findbugs reports (if the Jenkins Tasks Scanner Plugin is installed).
Archiving and the fingerprinting of the artifacts and attached artifacts generated by the Maven build (jar, sources jar, javadocs jar...)
Requires Surefire, Tycho, Frontend plugins during the Maven build.
Additionally, if Flaky Test Handler are installed, JUnits reports will be processed by these plugins.
Except the Frontend one, all these plugins publish a reportsDirectory property which can be used to find and import JUnit compatible reports. The Frontend plugin has another behaviour, so for detection to work, you have to set a REPORTS_DIRECTORY environment variable to the plugin (and reuse it in your Karma configuration, to be consistent) :
<plugin> <groupId>com.github.eirslett</groupId> <artifactId>frontend-maven-plugin</artifactId> <executions> <execution> ... <configuration> ... <environmentVariables> <REPORTS_DIRECTORY>${project.build.directory}/karma-reports</REPORTS_DIRECTORY> </environmentVariables> </configuration> </execution> </executions> </plugin>
Requires Jenkins FindBugs Plugin.
Publishing of the Findbugs reports generated by the Maven build
Requires the deprecated Concordion test report (since 3.0.0)
Requires the Concordion test reports.
Publish the Concordion reports generated by the maven-surefire-plugin:test and the `maven-failsafe-plugin:integration-test goals and located in the folder described by the system property `concordion.output.dir as documented in Maven Invoker Plugin test reports
Publish test reports generated by the Jenkins JGiven Plugin
Build the graph of dependencies between Jenkins pipelines and Maven artifacts in order to trigger downstream pipelines (when using the snapshotDependencies on downstream pipelines)
By default, all the publishers are enabled by default.
It is possible to change the default activation of a publisher navigating to the Global Tool Configuration screen.
It is possible to disable the default activation of publishers on a specific withMaven(){...} step using the publisherStrategy='EXPLICIT' attribute in the step withMaven(publisherStrategy='EXPLICIT'){...}.
The publishers can then be enabled explicitly in the withMaven(){...} step using the "publishers" attribute.
It is possible to use a marker file to temporarily disable the feature for a specific Maven build. Typically, used to disable a reporter for a specific build that would generate too much data for the default configuration of the reporter (e.g. too many generated artifacts...) or to workaround a bug in the "withMaven" waiting for a fix. These markers file must be located in the home directory of the build.
| Reporter | Configuration to disable the feature Since v2.3.0 |
Marker file to disable the feature |
|---|---|---|
Generated Artifact |
Since 3.11.0 more fine granular options: |
|
Generated JUnit reports |
|
|
Generated Coverage reports |
|
|
Generated Findbugs reports |
|
|
Tasks scanner report |
|
|
Dependencies Fingerprinting |
|
|
Concordion test report |
|
|
Maven Invoker Plugin test reports |
|
|
JGiven reports |
|
|
Maven Linker Publisher |
|
|
Pipeline Graph Publisher |
|
|
Default Maven settings can be defined globally and at the folder level.
Trigger downstream pipeline that depend on Maven artifact generated by upstream pipelines.
The upstream artifact must be generated in a withMaven(){} wrapping step to be detected by the triggering system
The downstream pipeline must have selected the build trigger Build whenever a SNAPSHOT dependency is built
The build trigger can be defined at the pipeline level (Build Triggers), at the multibranch pipeline level (Scan Repository Triggers) or at the GitHub Organization / Bitbucket Project level (Scan Organizations Triggers)
You have to manually trigger once the upstream pipeline, and the downstream pipeline so that the link between the pipelines based on the SNAPSHOT dependency is established
The dependency graph is, for the moment, optionally stored in an H2 embedded database ($JENKINS_HOME/jenkins-jobs/jenkins-jobs.mv.db). And there is support
for PostgreSQL and MySql as well (see details below)
trigger downstream 1 trigger downstream 2
Downstream Pipeline Trigger - Org Level Configuration
Thresholds are applied to define on which type of maven build the downstream pipelines are triggered
Threshold based on the status of the upstream pipeline (success, unstable, failure, no build, aborted).
By default, only builds with a success result will trigger downstream builds.
downstream pipeline trigger threshold build result
Threshold based on the Support of Maven Wrapper 'mvnw'
The Pipeline Maven Plugin works with withMaven() { sh "./mvnw clean deploy" }
The API for Maven reporters is still experimental. Please open a Request for Enhancement Jira issue to discuss how to add Maven reporters.
We want to quickly add reporters for CheckStyle...
To use a database you must first install the Pipeline Maven Plugin Database
Have a look at the Tools configuration:
The make a choice in available DAOs options:
For Configuration as Code users, these are the field to add into their yaml file daoClass and jdbcUrl
The Jenkins Pipeline Maven Plugin relies on a database to store its data (list of dependencies and of generated artifacts of each build...).
By default, the Jenkins Pipeline Maven Plugin uses an H2 embedded database, but it is recommend to use an external MySQL database.
Configuration steps to use a MySQL:
Create an empty MySQL database with a dedicated MySQL user with permissions for Data Manipulation Language actions (DML) and Data Definition Language (DDL) actions
Tested with MySQL up to 9.4, with MariaDB up to 12.1 and with Amazon Aurora MySQL 5.6
Install the Jenkins MySQL Database plugin
Navigate to Manage Jenkins / Manage Plugins / Available, select the MySQL Database plugin and click on Download now and install after restart
Configure the Pipeline Maven Plugin to use the created MySQL database
Create Jenkins credentials for the MySQL connection navigating to Credentials on the left menu
Navigate to Manage Jenkins / Global Tools Configuration and go to the Pipeline Maven Configuration
pipeline maven plugin configuration 1
In the Database configuration section, define the following.
JDBC URL: url of the database, e.g. jdbc:mysql://mysql.example.com/jenkins
JDBC Credentials: select the credentials of the MySQL database.
The Using a PostgreSQL Database
The Jenkins Pipeline Maven Plugin relies on a database to store its data (list of dependencies and of generated artifacts of each build...).
By default, the Jenkins Pipeline Maven Plugin uses an H2 embedded database, but it is recommended to use an external PostgreSQL or MySQL / MariaDB database.
Configuration steps to use a PostgreSQL:
Create an empty PostgreSQL database with a dedicated PostgreSQL user with permissions for Data Manipulation Language actions (DML) and Data Definition Language (DDL) actions
Tested with PostgreSQL up to 18
Install the Jenkins the HikariCP, comes with sensible default configuration values (see Known Limitations
docker.image('xxx').inside{...}
Maven and JDK installers do not work with
docker.image('xxx').inside{...} as the docker step does not allow the use of Tool Installer, the preinstalled Maven and JDK on the docker image will be auto-discovered and used.
withMaven() not supported in docker.image('xxx').inside{...} with old versions of the Docker enginewithMaven() not supported in docker.image('xxx').inside{...} with old versions of the Docker engine such as Docker 1.13.1 on CentOS7.
Any help to fix this bug is more than welcome.