×
Find plugins

Pipeline Maven Integration3.0.1Minimum Jenkins requirement: 2.46.3ID: pipeline-maven

 

Introduction

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.

Usage

An example pipeline script using the pipeline Maven plugin:

Maven build on a Linux agent
node{
  stage ('Build') {

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

    withMaven(
        // 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 reports and FindBugs reports
  }
}

Withn 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:

  • 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 allowing the replacement of server credentials and variable substitutions as configured in 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 settings.xml reference
    • Maven Settings File Path (mavenSettingsFilePath): Specify the path to a Maven settings.xml file on the build agent. The specified path can be absolute or relative to the workspace. 

    • If none of "mavenSettingsConfig" and "mavenSettingsFilePath" are defined, "withMaven(){}" will use the Maven settings defined in the Jenkins Global Tool Configuration if declared

  • Maven Global Settings

    • Maven Global Settings Config (globalMavenSettingsConfig): Select a Maven global settings file ID from 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: Java Options
    Shell-like environment variable expansions work in this field, by using the ${VARIABLE} syntax.
  • Maven Local Repository (mavenLocalRepo): Specify a custom local repository path. Shell-like environment variable expansions work with this field, by using the ${VARIABLE} syntax. Normally, Jenkins uses the local Maven repository as determined by Maven, by default ~/.m2/repository and can be overridden by <localRepository> in ~/.m2/settings.xml (see Configuring your Local Repository))
    This normally means that all the jobs that are executed on the same node shares a single Maven repository. The upside of this is that you can save the disk space, the downside is that the repository is not multi process safe and having multiple builds run concurrently can corrupt it. Additionally builds could interfere with each other by sharing incorrect or partially built artifacts. For example, you might end up having builds incorrectly succeed, just because your have all the dependencies in your local repository, despite that fact that none of the repositories in POM might have them.
    By using this option, Jenkins will tell Maven to use a custom path for the build as the local Maven repository by using -Dmaven.repo.local
    If specified as a relative path then this value will be resolved against the workspace root and not the current working directory.
    ie. $WORKSPACE/.repository if .repository value is specified.

(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:

  • maven: 'M3' 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 an specific settings.xml configuration from Config File Provider Plugin plugin, allowing the replacement of variables and credentials.

Features

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 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:

  • 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-10T16: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 Jenkins Config File Provider Plugin,
    details of the Jenkins credentials injected in the Maven build.
    • "withMaven(){}" step initialization: "[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', ...]"

Sample:

[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"

Maven Build Phases Publishers

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 Jenkins JUnit Plugin is installed)
  • Publish Findbugs reports (if the Jenkins FindBugs Plugin is installed)
  • Publish a report of the tasks ("FIXME" and "TODO") found in the java source code (if the Jenkins Tasks Scanner Plugin is installed)
  • Concordion test reports (since 3.0.0)

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

Reporter

Description

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)],...)

`.skip-archive-generated-artifacts`

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)],...)

`.skip-publish-junit-results`

Generated Findbugs reports

Publishing of the Findbugs reports generated by the Maven build

FindBugs Plugin

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

`.skip-publish-findbugs-results`

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)],...)

`.skip-task-scanner`

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 Plugin withMaven(options: [concordionPublisher(disabled: true)],...) `.skip-publish-concordion-results`
Maven Invoker Plugin test reports Publish test reports generated by the maven-invoker-plugin:run goal
Maven Invoker Plugin
withMaven(options: [invokerPublisher(disabled: true)],...) `.skip-publish-invoker-run`
JGiven reports Publish JGiven test reports JGiven Plugin withMaven(options: [jgivenPublisher(disabled: true)],...) `.skip-publish-jgiven-results`

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

Global Default Configuration

The default configuration of the Maven settings, global settings and the publishers can be defined in the "Global Tool 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

  • 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, exclusively stored in an H2 embedded database ("$JENKINS_HOME/jenkins-jobs/jenkins-jobs.mv.db"). Support for an external H2 database and then for alternate databases (PostgreSQL) is on the roadmap (see PipelineMavenPluginH2Dao.java)

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.
    • Threshold based on the Maven lifecycle phase reached in the Maven build of the upstream job ("package", "install", "deploy"). By default, only the maven builds who reach the "deploy" phase will trigger downstream builds.

Linux, Windows and MacOSX support

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

Maven build on a Windows agent
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
  }
}

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

FAQ

Does the Jenkins Pipeline Maven Plugin works with the "mvnw" wrapper?

withMaven() {
   // many features of withMaven() work with mvnw
   sh "./mvnw package"
}
...

Many features of "withMaven(){...}" work with Takari's Maven Wrapper "mvnw":

  • Generated artifact archiving and fingerprinting
  • Reports publishing: JUnit Surefire & FailSafe, FindBugs, Concordion, Maven Invoker Plugin, Open Tasks Scanner ("FIXME", "TODO"...)...
  • Downstream pipeline triggering

Unfortunately, "withMaven(){...}" cannot pass the following parameters to Takari's Maven Wrapper "mvnw":

  • JDK installation
  • Maven settings or global settings
  • Maven JVM opts
  • Maven local repository path

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:

  • Setting the environment variable "JENKINS_MAVEN_AGENT_DISABLED" to "true" in the job execution

 

...
withMaven() {
   sh """
export JENKINS_MAVEN_AGENT_DISABLED=true
mvn package
"""
}
...
withEnv(['JENKINS_MAVEN_AGENT_DISABLED=true']) {
   sh "mvn package"
}

 

  • Adding the system property "-Dorg.jenkinsci.plugins.pipeline.maven.eventspy.JenkinsMavenEventSpy.disabled=true" to the invocation of the mvn build

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"

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".

Sample:

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

withMaven(){
   mvn help:effective-settings
}

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.

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.

JENKINS-40484 - Getting issue details... STATUS

Changelog

3.0.1 (2017-10-04)

  • JENKINS-46511 Threshold to trigger downstream pipelines only if a Maven lifecycle phase has been executed (deploy or install or package)

  • JENKINS-46446 Build status should not be limited to SUCCESS for downstream triggering

  • JENKINS-47013 Exception parsing Spy log when Job name contains invalid XML characters (like "–")
  • JENKINS-46609 withMaven should detect when a maven build was interrupted instead of reporting an XML parsing exception

  • JENKINS-45887 automatically detect JGiven reports
  • JENKINS-47069 Downstream pipelines are not triggered when the artifact is an OSGi bundle and consumed as a jar

3.0.0 (2017-08-24)

  • JENKINS-44721 Trigger pipelines that depend on generated snapshot artifacts
    • select the build trigger "Build whenever a SNAPSHOT dependency is built" on the downstream pipelines
    • manually trigger once the upstream pipeline and once the downstream pipeline so that each of them is "registered" in the "pipeline dependency graph"
    • when the upstream and downstream jobs are registered, the following messages will be displayed in the build logs when an upstream pipeline triggers a downstream pipeline:
    • Message in the logs of the upstream pipeline build: "[withMaven] Scheduling downstream pipeline my-downstream-pipeline#7..."
    • Message in the build logs of the downstream pipeline: "Started by upstream project 'my-upstream-pipeline' build number 5"
  • JENKINS-45674 Automatically publish Concordion reports
  • JENKINS-45265 Automatically publish test reports generated by the maven-invoker-plugin
  • JENKINS-46342 Passwords injected in Maven settings should be masked in the build logs
  • JENKINS-46084 more fixes for "IllegalArgumentException : Cannot relativize '...' relatively to ...'" with symlinks

2.5.2

  • JENKINS-45221 Use case insensitive path when computing the workspace relative path

2.5.1

  • JENKINS-45024 Use org.eclipse.aether.artifact.Artifact#isSnapshot() to identify snapshot versions

  • JENKINS-40484 Better troubleshooting messages

2.5.0

  • JENKINS-43094 Support Fingerprinting of consumed dependencies

  • JENKINS-44807 Generated artifacts are only fingerprinted as fingerprint.original but not as fingerprint.usage

2.3.1

  • JENKINS-44226 Support junit testDataPublishers
    • Publishing of junit test attachments are enabled by default if the junit-attachments-plugin is installed.
    • Junit test attachments can be disabled using options: [junitPublisher(ignoreAttachments: true)]. Sample:

 

junitPublisher ignore attachments sample
withMaven(
        maven:"maven-3.3.9", 
        mavenSettingsConfig: 'my-maven-settings',
        options: [junitPublisher(ignoreAttachments: true)]) {
            
    sh "mvn clean install"
}
  • JENKINS-44386 Add configuration options to the OpenTasksPublisher
    • Sample
openTasksPublisher options sample
withMaven(options:[openTasksPublisher(
       pattern:'src/main/java', excludePattern:'src/main/java/excluded',
       ignoreCase:true, asRegexp:false, 
       lowPriorityTaskIdentifiers:'minor', normalPriorityTaskIdentifiers:'todo', highPriorityTaskIdentifiers:'fixme')]) {

           sh 'mvn package verify'
}

 

 

2.3.0

  • Add configuration options to disable the publishers. Code look like:
Options to disable publishers
withMaven(
  maven:"maven-3.3.9",
    options: [
	  findbugsPublisher(disabled: true), 
	  artifactsPublisher(disabled: true), 
	  junitPublisher(disabled: true), 
	  openTasksPublisher(disabled: true)]) {
	  
   sh "mvn clean deploy"
}

 

2.2.1

  •  JENKINS-44088 Fix bug when Windows agent use the "/" file separator instead of the "\" file separator

2.2.0

2.1.0

  • JENKINS-39407 - Use Maven Global Settings and Maven Settings defined at the Jenkins global level if not specified in the pipeline withMaven(){...} step

2.0.3

  • JENKINS-43714 - withMaven thinks that "mvn test" generates a jar file causing a FileNotFoundException trying to archive it 

  • JENKINS-43678 - Exception archiving and fingerprinting Maven artifact

  • JENKINS-43616 - Flattened pom throws errors

2.0.2

  • JENKINS-43261 - Bug - withMaven parses emtpy EventSpy logfiles
  • JENKINS-43529 - Bug - Disabled Jenkins Maven Event Spy generates an invalid XML build log file

  • JENKINS-43491 - Enhancement - Feature flag to archive the Maven build logs for troubleshooting purpose (marker file ".archive-jenkins-maven-event-spy-logs")

2.0.1

2.0

  • Detect Maven build details and process the outputs of the build:
  • More detailed traceability of the Maven settings used for the build

0.7

  • High severity security release, please read advisory for SECURITY-309. If you are running 2.0-beta you should update at least to 2.0-beta-6

0.6

  • Wrong release, no changes over the previous.

0.5

  • JENKINS-39916 upgrade to config-file-provider:2.15.1 and support definition of Maven settings file and global settings file at the folder level

0.4

  • JENKINS-39134 -  Fix exception after resuming a build
  • Allow defining global Maven settings by config file (globalMavenSettingsConfig) and by file path (globalMavenSettingsFilePath)
  • JENKINS-40142 - Snippet generator was creating parameters even if they were left empty

0.3

  • JENKINS-38709 - Console log filter was being overriden, which didn't allow the use of other steps which filtered the logs (ie. MaskPasswordBuildWrapper, AnsiColorBuildWrapper, etc.)
  • MAVEN_TERMINATE_CMS is no longer overriden. Setting MAVEN_TERMINATE_CMS to "on" causes Windows batch execution to be completed after the first call to mvn, as mvn will use exit instead of exit /b

0.2

  • First stable release
  • JENKINS-37613 - Unify naming convention for tool installation. The mavenInstallation parameter was renamed to maven.

0.1-beta

  • Initial version
ArchivesGet past versions
Labels
Previous Security Warnings