Provides Maven integration with Pipeline Plugin by using the withMaven step, which configures a maven environment to use within a pipeline job by calling sh mvn or bat mvn.


An example pipeline script using the pipeline Maven plugin:

  stage ('Build') {

    git url: 'https://github.com/cyrille-leclerc/multi-module-maven-project'

        // Maven installation declared in the Jenkins "Global Tool Configuration"
        maven: 'M3',
        // Maven settings.xml file defined with the Jenkins Config File Provider Plugin
        // Maven settings and global settings can also be defined in Jenkins Global Tools Configuration
        mavenSettingsConfig: 'my-maven-settings',
        mavenLocalRepo: '.repository') {

      // Run the maven build
      sh "mvn clean install"

    } // withMaven will discover the generated Maven artifacts, JUnit Surefire & FailSafe & FindBugs reports...

Within a node or a docker.image block, create a withMaven block to setup 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:

(info) mavenSettingsConfig and globalMavenSettingsConfig use the ID, not the name, of the Maven settings file (resp Maven Global Settings file).

The Pipeline Syntax snippet code generator can be used to assist on generating the withMaven step parameters

In the above example the following parameters are use to configure maven:


Sensible default Maven parameters

The Maven parameters that are useful on a build server, "--batch-mode" ("-B") and "--show-version" ("-V") are enable by default, no need to add them in your mvn invocations.

Maven Settings Support

The "withMaven()" pipeline step will setup the Maven settings file and global settings file either explicitly using the attributes of the "withMaven(){}" step declaration or implicitly using the Maven Global Settings and Settings files defined at the folder level or in the Jenkins Global Tools Configuration.

Using implicit declaration, Jenkins administrators can simplify the work of pipeline authors hiding the "boilerplate" to declare the credentials of the Git, Nexus, Artifactory... servers and all the needed proxies, mirrors...

Traceability of Maven builds

The "withMaven()" pipeline step will capture in the logs of the build all the details of the execution:


[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-10T16: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"

Report Publishers

Maven build executions inside the "withMaven(){...}" will be detected and Jenkins will transparently

(info) The detection of Maven builds require to use Maven 3.2+.



Required Jenkins Plugin (1)

Configuration to disable the feature

Since v2.3.0 (2)

Marker file to disable the feature (3)

Generated Artifact

Archiving and the fingerprinting of the artifacts and attached artifacts generated by the Maven build (jar, sources jar, javadocs jar...)

withMaven(options: [artifactsPublisher(disabled: true)],...)


Generated JUnit, Surefire and FailSafe reports

Publishing of the JUnit, Surefire and FailSafe reports generated by the Maven build

JUnit Plugin

withMaven(options: [junitPublisher(disabled: true)],...)


Generated Findbugs reports

Publishing of the Findbugs reports generated by the Maven build

FindBugs Plugin

withMaven(options: [findbugsPublisher(disabled: true)],...)


Tasks scanner report

Publishing of a report of the "FIXME" and "TODO" tasks found in the java source code. The keywords can be configured.

Jenkins Tasks Scanner Plugin

withMaven(options: [openTasksPublisher(disabled: true)],...)


Dependencies Fingerprinting

(since 2.5.0)

Fingerprint the Maven dependencies.

By default only the snapshot dependencies of scope compile, runtime and provided are fingerprinted.

withMaven(options: [dependenciesFingerprintPublisher(disabled: true)],...)`.skip-fingerprint-maven-dependencies`

Concordion test report

(since 3.0.0)

Publishing of 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 Concordion > Integration > Java > Maven

HTML Publisher PluginwithMaven(options: [concordionPublisher(disabled: true)],...)`.skip-publish-concordion-results`
Maven Invoker Plugin test reportsPublish test reports generated by the maven-invoker-plugin:run goal
Maven Invoker Plugin
withMaven(options: [invokerPublisher(disabled: true)],...)`.skip-publish-invoker-run`
JGiven reportsPublish JGiven test reportsJGiven PluginwithMaven(options: [jgivenPublisher(disabled: true)],...)`.skip-publish-jgiven-results`
JaCoCo Code CoveragePublish JaCoCo Code CoverageJaCoCo Plugin

withMaven(options: [jacocoPublisher(disabled: true)],...)

(1) Jenkins Plugin to publish the reports on the Jenkins build page. If the plugin is not installed, then the MAven report is ignored.

(2) Download pipeline-maven-2.3.0-beta-1.hpi

(3) 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 marker file must be located in the home directory of the build.

Implicit or Explicit activation of Publishers

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

Default Configuration

Default Maven settings can be defined globally and at the folder level.

Global Default Configuration

In the "Global Tool Configuration" screen

Folder Level Configuration

In the Folder "configuration" screen

Trigger downstream pipeline when a snapshot is built (since 3.0.0)

Trigger downstream pipeline that depend on Maven artifact generated by upstream pipelines.

(info) Notes

Downstream Pipeline Trigger - Org Level Configuration

Linux, Windows and MacOSX support

The Pipeline Maven Plugin works with Linux, Windows and MacOSX build agents.

node ("windows") {
  stage ('Build') {

    git url: 'https://github.com/cyrille-leclerc/multi-module-maven-project'

    withMaven(...) {

      bat "mvn clean install"

    } // withMaven will discover the generated Maven artifacts, JUnit Surefire & FailSafe reports and FindBugs reports

Support of Takari's Maven Wrapper 'mvnw' (since 3.0.3)

The Pipeline Maven Plugin works with Takari's Maven wrapper 'mvnw'.

withMaven(...) {
   sh "./mvnw clean deploy"

Adding more Maven Reporters

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, Jacoco...


Using a MySQL Database (since 3.6.0)

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:


How to use the Pipeline Maven Plugin with Docker? (since version 3.0.3)

Since the version 1.14 of the Docker Pipeline plugin, "withMaven" requires to

If omitted, the Maven settings file and Mven global settings file will not be injected in the Maven execution.

Using "withMaven" with "docker.image(...).inside{...}" and a Jenkins Scripted Pipeline 

node("linux-agent-running-docker") { // Linux agent with the Docker daemon
    docker.image('maven').inside { // Docker image with Maven installed
        withMaven(...) {
            git "https://github.com/cyrille-leclerc/my-jar.git"
            sh "export PATH=$MVN_CMD_DIR:$PATH && mvn clean deploy" // 'mvn' command: need to add the $MVN_CMD_DIR to $PATH


node("linux-agent-running-docker") { // Linux agent with the Docker daemon
    docker.image('openjdk:8-jdk').inside { // Docker image with Java installed
        withMaven(...) {
            git "https://github.com/cyrille-leclerc/my-jar.git"
            sh "./mvnw clean deploy" // 'mvnw' command (e.g. "./mvnw deploy")

Using "withMaven" with "docker.image(...).inside{...}" to a Jenkins Declarative Pipeline 

TODO provide a sample with Jenkins Declarative Pipeline


Sample message displayed in the build logs when using withMaven in a Docker Pipeline execution environment

Warning message displayed in the logs when invoking withMaven within Docker Pipeline:

[withMaven] WARNING: "withMaven(){...}" step running within "docker.image('image').inside {...}". Since the Docker Pipeline Plugin version 1.14, you MUST:
[withMaven] * Either prepend the 'MVN_CMD_DIR' environment variable to the 'PATH' environment variable in every 'sh' step that invokes 'mvn' (e.g. "sh 'export PATH=$MVN_CMD_DIR:$PATH && mvn clean deploy' "). 
[withMaven] * Or use Takari's Maven Wrapper (e.g. "sh './mvnw clean deploy'")
[withMaven] See Pipeline Maven Plugin FAQ.

How to disable the Maven Event Spy injected by the Pipeline Maven Plugin in Maven builds?

It may be convenient to temporarily disable the Maven Event Spy of the Jenkins Pipeline Maven plugin, for example for troubleshooting purpose.

You can disable the Maven Event Spy of the Jenkins Pipeline Maven plugin (making it no-op) doing one of the following:

withMaven() {
   sh """
mvn package
   sh "mvn package"

Why do I see messages "[WARNING] Picked up JAVA_TOOL_OPTIONS..." in the build logs?

The Jenkins Pipeline Maven Plugin uses the "JAVA_TOOL_OPTIONS" environment variable to pass options to subsequent Maven builds such as the actual release build when invoking "mvn release:prepare release:perform". The plugins passes the properties "-Dmaven.ext.class.path" and "-Dorg.jenkinsci.plugins.pipeline.maven.reportsFolder".

When using the "JAVA_TOOL_OPTIONS", the JVM outputs a message during its initialization.

With the Jenkins Pipeline Maven Plugin, this message looks like:

[WARNING] Picked up JAVA_TOOL_OPTIONS: -Dmaven.ext.class.path="/path/to/workspace/...@tmp/withMaven.../pipeline-maven-spy.jar" -Dorg.jenkinsci.plugins.pipeline.maven.reportsFolder="/path/to/workspace/...@tmp"

(info) It is not possible to disable this warning message

How can I troubleshoot problems of trigger of downstream pipelines

How do I capture the log file generated by the Jenkins Maven Event Spy

You can archive the XML log file generated by the Jenkins Maven Event Spy creating the marker file ".archive-jenkins-maven-event-spy-logs".


withMaven() {
	sh "mvn package"
	writeFile file: '.archive-jenkins-maven-event-spy-logs', text: ''
} // will discover the marker file ".archive-jenkins-maven-event-spy-log" and will archive the maven event spy log file maven-spy-....log	

How do I check the Maven settings in use by my build

You can dump the effective Maven settings of your pipeline using the Maven Help plugin and the "help:effective-settings" goal

   mvn help:effective-settings

How can I reduce the footprint of the database of the Jenkins Pipeline Maven Plugin?

The Jenkins pipeline Maven plugin uses a database to trigger downstream pipelines when a snapshot is built.

For production grade deployments, a MySQL database is needed instead of the embedded H2 database. My SQL 5.6+, Amazon Aurora MySQL and MariaDB 10.2+ have been successfully tested.

To reduce the usage of the database, disable the "Pipeline Graph Publisher" navigating to "Manage Jenkins / Global Tool Configuration / Pipeline Maven Configuration" then clicking on "Add Publisher Options", selecting "Pipeline Graph Publisher" and checking the "disabled" checkbox.

Why do I see messages "[withMaven] One or multiple Maven executions have been ignored..." in the build logs?

The message "[withMaven] One or multiple Maven executions have been ignored by the Jenkins Pipeline Maven Plugin because they have been interrupted before completion..." because one or several Maven execution (e.g. "mvn deploy") have been interrupted before they could gracefully complete.
The event "org.apache.maven.eventspy.EventSpy#close()" has not been invoked on the Maven event spies.
This interruption usually happens because the mvn process has been killed by the Operating System, typically for memory constraints in Docker or cgroups environments. Another cause is a "kill -9" during the build.

Why do I see messages "javax.xml.parsers.FactoryConfigurationError: Provider for class javax.xml.parsers.DocumentBuilderFactory cannot be created"

This error is caused by the installation of another plugin that pulls an outdated version of Apache Xerces. That pulls a version of Apache Xerces that is not compatible with the version of the JVM. Typically, Xerces 2.6 will not be compatible with a JDK 8 due to changes in the JAXP API (sample: ).

The solution is to get this plugin updated so that it uses a more recent of Xerces that would be compatible with the JDK.

To identify the plugin that is pulling an outdated version of a JAXP implementation (typically Xerces), navigate to the Jenkins Script Console ("Manage Jenkins" then "Script Console") and execute the following groovy script:

String className = "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"

Class klass
try {
  klass = Class.forName(className)
} catch (Exception e) {
  println("Exception trying to load " + className + " from the system classloader, try the thread context classloader " + e)
  // contextClassLoader should not work but let's try it.
  klass = Class.forName(className, false, Thread.currentThread().getContextClassLoader())

java.security.CodeSource codeSource = klass.getProtectionDomain().getCodeSource()

if (codeSource == null) {
  println(klass.toString() + " -> source not found")
} else {
  println(klass.toString() + " -> " + codeSource.getLocation());

The output message will show from which plugin the XercesParser is loaded. Sample with a plugin "my_plugin" that would load an outdated 2.6.2 version of Xerces:

class org.apache.xerces.jaxp.DocumentBuilderFactoryImpl -> file:/var/lib/jenkins/plugins/my_plugin/WEB-INF/lib/xercesImpl-2.6.2.jar 

Known Limitations

Maven and JDK installation not supported in 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 engine

withMaven() 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.


See https://github.com/jenkinsci/pipeline-maven-plugin/releases