Skip to content

How to add the common CI pipelines and pre-commit configuration to an existing Java project

The common CI pipeline and Java Maven pipeline templates provide a number of common jobs useful for Java based projects.

This page shows you how to add these jobs to a pipeline for an existing Java project.

Add the CI configuration

Update your .gitlab-ci.yml file and add the following pipeline templates:

.gitlab-ci.yml
include:
  - project: "uis/devops/continuous-delivery/ci-templates"
    file: "/auto-devops/common-pipeline.yml"
    ref: "{replace with the latest ci-templates repository tag}"
  - project: "uis/devops/continuous-delivery/ci-templates"
    file: "/auto-devops/maven.gitlab-ci.yml"
    ref: "{replace with the latest ci-templates repository tag}"

variables:
  # Add this variable if you don't have a Dockerfile in the repository and/or
  # want to disable automatic image building.
  BUILD_DISABLED: "1"

  # Add this variable if your project does not need to run 'mvn deploy'
  # to publish build artifacts to a GitLab Maven Repository
  MAVEN_DEPLOY_DISABLED: "1"

  # Add this variable if your project does not need to run 'mvn verify'
  # to run tests in your pipeline
  MAVEN_VERIFY_DISABLED: "1"

  # Add this variable if you do not need to retrieve GitLab Access Tokens
  # used to download Maven dependencies from a configured Maven Repository in GitLab
  MAVEN_ACCESS_TOKENS_DISABLED: "1"

Using maven.gitlab-ci.yml with release-it to automate your releases

Note

This is required if you are using gitlab.maven-ci.yml template v7.19.2 or later.

The maven.gitlab-ci.yml template from v7.19.2 onwards has been updated to support automating your releases using release-it. For further details see How to enable automated GitLab releases.

Before this update, the job to publish your artifacts to a GitLab Package Registry ran as the last job in your merge pipeline. After this change, the publish job now runs in a tag pipeline, after release-it has determined the next incremental version and pushed a new tag.

From v7.19.2 onwards, you need to add the release-it template and a .release-it.json configuration file in your project.

Adding the release-it CI template

Add the release-it CI template to your .gitlab-ci.yml :

.gitlab-ci.yml
include:
  - project: "uis/devops/continuous-delivery/ci-templates"
    file: "/auto-devops/common-pipeline.yml"
    ref: "{replace with the latest ci-templates repository tag}"
  - project: "uis/devops/continuous-delivery/ci-templates"
    file: "/auto-devops/maven.gitlab-ci.yml"
    ref: "{replace with the latest ci-templates repository tag}"
  - project: "uis/devops/continuous-delivery/ci-templates"
    file: "/auto-devops/release-it.yml"
    ref: "{replace with the latest ci-templates repository tag}"

Adding the required release-it configuration

For Java and Maven projects we do not need release-it to publish to GitLab since this is performed by the package-registry-push job. Add the following .release-it.json file to the root of your project:

.release-it.json
{
  "git": {
    "commitMessage": "chore(release): ${version}"
  },
  "gitlab": {
    "release": true,
    "releaseName": "${version}",
    "publish": "false"
  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "infile": "CHANGELOG.md",
      "header": "# Changelog",
      "preset": {
        "name": "conventionalcommits"
      }
    }
  }
}

Note

This configuration differs from the configuration documented on the How to enable automated GitLab releases page, by adding "publish": "false" property to tell release-it not to publish to GitLab

How to disable optional features

The maven.gitlab-ci.yml template includes a number of common jobs that are enabled by default.

If your CI pipeline for your project does not need to run any of the included jobs, disable them by including the specific variable for the job you need to disable as shown above.

Retrieving Maven Dependencies from a shared GitLab Package Registry

If your project needs to retrieve Jar dependencies from a GitLab Package Registry configured in your Maven pom.xml:

  • this feature is enabled in .maven.gitlab-ci.yml by default, do not add the MAVEN_ACCESS_TOKENS_DISABLED variable as shown above. If you do not need to access a GitLab Package Registry, disable this feature by adding MAVEN_ACCESS_TOKENS_DISABLED: "1"

  • Configure a Maven Repository url in the root pom.xml in your Java project by adding the configuration shown in the How to Configure Maven Package Registries guide. Ignore the other sections on that page as they cover how to configure access for local development only.

  • Ensure your project was created using the GitLab Project Factory, and you have configured your product-vars to configure access to a group_deploy_token, where:

    • [GROUP-ID] is the GitLab group id that contains the project and it's Package Registry that your project needs to access to retrieve dependant Jars. Note that this group id must be the same as the id in the url that you configured in your project's pom.xml in the Maven Repository step above.

    • [GCP-META-PROJECT-ID] is the Project Id for the meta project for your system in GCP

group_deploy_tokens = {
  deploy = {
    group_id     = "[GROUP-ID]"
    access_level = "maintainer"
    scopes       = ["read_package_registry", "write_package_registry"]
    iam_policy = {
      "roles/secretmanager.secretAccessor" : [
        "serviceAccount:gitlab-token-accessor@[GCP-META-PROJECT-ID].iam.gserviceaccount.com",
      ]
    }
  }
}
  • add a ci_settings.xml file in the root of your project with the following content:
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <servers>
    <server>
      <id>gitlab-maven</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Deploy-Token</name>
            <value>${GITLAB_TOKEN}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

Note that the Deploy-Token name must be used, and ${GITLAB_TOKEN} is replaced at runtime with the value of the GitLab Access Token retrieved by a script in maven.gitlab-ci.yml.

Required additional configuration needed for gitlab.maven-ci.yml template prior to v7.5.1

Note

Ignore this section if you are using gitlab.maven-ci.yml template v7.5.1 or later.

This configuration is now included in v7.5.1 of the template and is no longer needed in your project's .gitlab-ci.yml if you are using version >= v7.5.1.

If you are using an prior version of gitlab.maven-ci.yml template before v7.5.1 it is required that you also add the following configuration:

  • extend the build job in your .gitlab-ci.yml to use a provided script to retrieve GitLab Access Tokens:
#add runner tag to maven hidden job
.maven:
  tags:
    - $GKE_RUNNER_TAG

build:
  before_script: !reference [.maven.deploy_tokens]
  tags:
    - $GKE_RUNNER_TAG

Note that tag value $GKE_RUNNER_TAG must be added to use a GitLab Runner on GKE which has access to retrieve secrets from Secrets Manager.

Add the google-java-format pre-commit plugin

The google-java-format pre-commit plugin should also be added to the project.

IDE formatter configuration

Plugins for the google-java-format code formattter are available for most IDEs - download and install from the following links: