Pipeline Maven Integration

See demos on the Configuration as Code:

https://github.com/jenkinsci/configuration-as-code-plugin/tree/master/demos/pipeline-maven

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.

Please note this is NOT part of this plugin, this is the Maven plugin configuration, but we depend on it.

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…​

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:

• Version of the JVM

  • withMaven(){} step initialization:

• mvn executable invocation:

• Version of Maven

  • withMaven(){} step initialization:

• mvn executable invocation:

• Name or path of the Maven settings.xml and Maven global settings.xml file.

  • withMaven(){} step initialization:

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

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)

• Concordion test reports (since 3.0.0)

• And more (see below) …​

Generated Artifact

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

Generated JUnit reports

Requires Jenkins JUnit Plugin. If the plugin is not installed, then the Maven report is ignored.

Publishing of the JUnit reports generated from the Surefire, FailSafe, Tycho, Karma or Frontend plugins during the Maven build. Additionally, if JUnit Attachments or 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>

Generated Findbugs reports

Requires the deprecated Jenkins FindBugs Plugin.

Publishing of the Findbugs reports generated by the Maven build

Tasks scanner report

Requires the deprecated Jenkins Tasks Scanner Plugin

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

Dependencies Fingerprinting (since 2.5.0)

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

Concordion test report (since 3.0.0)

Requires the Jenkins HTML Publisher Plugin

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

Maven Invoker Plugin test reports

Publish test reports generated by the maven-invoker-plugin:run goal

JGiven reports

Requires the Jenkins JGiven Plugin

Publish JGiven test reports

Maven Linker Publisher

Publish the Maven report on the pipeline build GUI (list of dependencies, produced artifacts, downstream & upstream pipelines).
This publisher should be renamed "Maven Build Report Publisher".
A reason to disable this publisher is typically to not "pollute" the build screen with Maven invocations when Maven is used as a utility (e.g. invocations of "maven-help-plugin:3.2.0:evaluate"…​)

Pipeline Graph Publisher

Build the graph of dependencies between Jenkins pipelines and Maven artifacts in order to trigger downstream pipelines (when using the snapshotDependencies on downstream pipelines)

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

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

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

The Pipeline Maven Plugin works with Maven Wrapper 'mvnw'.

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 8.1, with MariaDB up to 11.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

  • 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 parameters recommended by the Hikari Connection Pool team are used by default for the MySQL connections and for the datasource (max pool size:10, server side prepared statements cache with 250 entries…​). To overwrite these defaults, click on the Advanced Database Configuration button.

  • Click on Validate Database Configuration button to verify that the connection is successful.

  • Click on Save.

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 16

• Install the Jenkins the PostgreSQL API plugin

  • Navigate to Manage Jenkins / Manage Plugins / Available, select the PostgreSQL API plugin and click on Download now and install after restart.

• Configure the Pipeline Maven Plugin to use the created PostgreSQL database

  • Create Jenkins credentials for the PostgreSQL connection navigating to Credentials on the left menu

  • Navigate to Manage Jenkins / Global Tools Configuration and go to the Pipeline Maven Configuration

  • In the Database configuration section, define the following

    • JDBC URL: url of the database, e.g. `jdbc:postgresql://postgresql.example.com:5432/jenkins

    • JDBC Credentials: select the credentials of the PostgreSQL database

    • The underlying datasource, HikariCP, comes with sensible default configuration values (see here). To overwrite these defaults, click on the Advanced Database Configuration button.

  • Click on Validate Database Configuration button to verify that the connection is successful.

  • Click on Save.

  • Navigate to Manage Jenkins / Global Tools Configuration and go to the Pipeline Maven Configuration to verify that the database connection is successful, and the database tables have been created (see screenshot above).

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 such as Docker 1.13.1 on CentOS7.

Any help to fix this bug is more than welcome.

JENKINS-40484 - Getting issue details…​ STATUS