README.md

GitLab CI template for Maven

This project implements a generic GitLab CI template for Maven.

It provides several features, usable in different modes (by configuration).

Usage

In order to include this template in your project, add the following to your gitlab-ci.yml:

include:
  - project: 'to-be-continuous/maven'
    ref: '3.1.3'
    file: '/templates/gitlab-ci-maven.yml'

Global configuration

The Maven template uses some global configuration throughout all jobs.

Name	description	default value
MAVEN_IMAGE	The Docker image used to run Maven ⚠️ set the version required by your project	maven:latest
MAVEN_PROJECT_DIR	Maven projet root directory	.
MAVEN_CFG_DIR	The Maven configuration directory	.m2
MAVEN_OPTS	Global Maven options	-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=${MAVEN_CFG_DIR}/repository -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true
MAVEN_CLI_OPTS	Additional Maven options used on the command line	--no-transfer-progress --batch-mode --errors --fail-at-end --show-version -DinstallAtEnd=true -DdeployAtEnd=true

About $MAVEN_CFG_DIR

This variable is used to define the Maven configuration directory. It is used for two (2) purposes:

• in case a Maven settings file (settings.xml) is found, the template automatically uses it (using the -s option on command line),
• the cache policy declares the ${MAVEN_CFG_DIR}/repository directory as cached (not to download Maven dependencies over and over again).

If you have a good reason to do differently, you'll have to override the MAVEN_CLI_OPTS variable as well as the cache policy.

Jobs

mvn-build job

The Maven template features a job mvn-build that performs build and tests at once. This stage is performed in a single job for optimization purpose (it saves time) and also for test jobs dependency reasons (some test jobs such as SONAR analysis have a dependency on test results).

It uses the following variable:

Name	description	default value
MAVEN_BUILD_ARGS	Maven arguments for the build & test job	org.jacoco:jacoco-maven-plugin:prepare-agent verify org.jacoco:jacoco-maven-plugin:report

About Code Coverage

With its default arguments, the GitLab CI template for Maven forces the use of JaCoCo Maven Plugin to compute code coverage during unit tests execution.

In addition it makes the necessary to integrate code coverage stats into your GitLab project: report badge and viewable in merge requests.

If yo want to fix the JaCoCo plugin version or tweak the default configuration, you may have to configure the JaCoCo Maven Plugin in your pom.xml, but be aware of the following:

• do not declare JaCoCo executions for prepare-agent and report goals as each would run twice during unit tests (not necessarily with the expected configuration). If you really need to do so anyway, you'll have to override the $MAVEN_BUILD_ARGS variable to remove the explicit invocation to JaCoCo goals.
• make sure the report goal computes a CSV report, that is used by the Maven template to compute the global coverage stat.

More info:

• Maven Surefire Plugin
• surefire:test parameters

SonarQube analysis job

This job is disabled by default and performs a SonarQube analysis of your code.

It is bound to the test stage, and uses the following variables:

Name	description	default value
SONAR_HOST_URL	SonarQube server url	none (disabled)
🔒 SONAR_TOKEN	SonarQube authentication token (depends on your authentication method)	none
🔒 SONAR_LOGIN	SonarQube login (depends on your authentication method)	none
🔒 SONAR_PASSWORD	SonarQube password (depends on your authentication method)	none
SONAR_BASE_ARGS	SonarQube analysis arguments	sonar:sonar -Dsonar.links.homepage=${CI_PROJECT_URL} -Dsonar.links.ci=${CI_PROJECT_URL}/-/pipelines -Dsonar.links.issue=${CI_PROJECT_URL}/-/issues
SONAR_QUALITY_GATE_ENABLED	Set to true to enable SonarQube Quality Gate verification. Uses sonar.qualitygate.wait parameter (see doc).	none (disabled)

Automatic Branch Analysis & Merge Request Analysis

This template relies on SonarScanner's GitLab integration, that is able to auto-detect whether to launch Branch Analysis or Merge Request Analysis from GitLab's environment variables.

⚠️ This feature also depends on your SonarQube server version and license. If using Community Edition, you'll have to install the sonarqube-community-branch-plugin to enable automatic Branch & Merge Request analysis (only works from SonarQube version 8).

⚠️ Merge Request Analysis only works if you're running Merge Request pipeline strategy (default).

mvn-dependency-check job

This job enables a manual Dependency-Check analysis.

It is bound to the test stage, and uses the following variables:

Name	description	default value
MAVEN_DEPENDENCY_CHECK_ARGS	Maven arguments for Dependency Check job	org.owasp:dependency-check-maven:check -DretireJsAnalyzerEnabled=false -DassemblyAnalyzerEnabled=false

A Dependency Check is a quite long operation and therefore the job is configured to be ran manually by default.

However, if you want to enable an automatic Dependency-Check scan, you will have to override the rules keyword for the mvn-dependency-check job.

Furthermore, if you want to upload Dependency-Check reports to SonarQube, you have to:

• Move mvn-dependency-check to the build stage
• Add -Dformats=html,json,xml to MAVEN_DEPENDENCY_CHECK_ARGS to output reports
  • HTML report to read the report on SonarQube UI
  • JSON report to create SonarQube issues from the report
  • XML report to import into DefectDojo security dashboard
• Add -Dsonar.dependencyCheck.htmlReportPath and -Dsonar.dependencyCheck.jsonReportPath with the paths of the generated html and json reports to SonarQube arguments.

More info:

• Maven Dependency-Check Plugin

mvn-forbid-snapshot-dependencies job

This job checks if the project has release-only dependencies, i.e., no _*-SNAPSHOT_ versions, using the Maven Enforcer plugin.

Failure is allowed in feature branches.

It is bound to the test stage, and uses the following variables:

Name	description	default value
MVN_FORBID_SNAPSHOT_DEPENDENCIES_DISABLED	Set to true to disable this job	none

mvn-snapshot & mvn-release jobs

These jobs are disabled by default and perform, respectively, the following: