Fork us on GitHub
×
Find plugins

Pipeline Maven Integration2.0Minimum Jenkins requirement: 1.642.4ID: pipeline-maven

Plugin Information

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:
 

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:

node{
  stage ('Build') {

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

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

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

    } // withMaven will discover the generated Maven artifacts, JUnit 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 Config (mavenSettingsConfig): Select a Maven settings file ID from Config File Provider Plugin allowing the replacement of server credentials 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 a Maven settings.xml file. The specified path can be absolute or relative to the workspace. Shell-like environment variable expansions work in this field, by using the ${VARIABLE} syntax. The file existence is checked on the build agent, if found, that one is used. If not found it will be checked on the master. 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. These include values such as the local repository location, alternate remote repository servers, and authentication information.
    There are two locations where a settings.xml file per default may live:
    • The Maven install - default: $M2_HOME/conf/settings.xml
    • A user's install - default: ${user.home}/.m2/settings.xml
      The former settings.xml are also called global settings, the latter settings.xml are referred to as user settings. If both files exists, their contents gets merged, with the user-specific settings.xml being dominant.
  • Maven Global Settings Config (globalMavenSettingsConfig): Select a global Maven settings file ID from Config File Provider Plugin.
  • Maven Global Settings File Path (globalMavenSettingsFilePath): Specify a global Maven settings.xml file. The specified path can be absolute or relative to the workspace. Shell-like environment variable expansions work in this field, by using the ${VARIABLE} syntax.
  • 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.

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

Traceability of Maven builds (since v2.0)

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

  • Version of the JVM
    • Plugin initialization: "[withMaven] use JDK installation JDK8""
    • mvn executable invocation: "Java version: 1.8.0_102, vendor: Oracle Corporation""
  • Version of Maven
    • Plugin 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.
    • Plugin 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.
    • Plugin 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-aws-home/tools/hudson.tasks.Maven_MavenInstallation/M3
Java version: 1.8.0_102, vendor: Oracle Corporation
Java home: /home/ubuntu/jenkins-aws-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 Reporters (since v2.0)

Maven build executions inside the "withMaven(){...}" wil 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)

The detection of Maven builds require to use Maven 3.2+.

(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) Experimental feature.
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.

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

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

Known Limitations

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.

Changelog

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