Maven Migration from Jenkins to GitLab CI/CD

The transition from a legacy Jenkins environment to a modern GitLab CI/CD architecture represents a fundamental shift in how Java Maven projects are integrated and delivered. For many organizations, the journey begins with a Maven build that has historically relied on a persistent Jenkins agent—a static piece of infrastructure where Maven and the Java Development Kit (JDK) were pre-installed. This approach, while functional, often leads to "snowflake servers" where the environment is difficult to replicate. GitLab CI/CD replaces this with a dynamic, configuration-as-code model defined in a .gitlab-ci.yml file, enabling a shift toward ephemeral runners and containerized build environments.

When migrating a Maven build, the core objective is to replicate the standard build lifecycle: testing the code, packaging the executable, and installing the artifact into a local repository. In the Jenkins ecosystem, this is often achieved through three primary methods: Freestyle projects using shell execution, Freestyle projects utilizing the Maven task plugin, or the more modern Declarative Pipelines defined in a Jenkinsfile. Regardless of the specific Jenkins implementation, the underlying goal remains the execution of mvn test, mvn package, and mvn install. The migration to GitLab CI/CD does not merely copy these commands; it transforms them into a structured pipeline of jobs and stages, leveraging Docker images and sophisticated caching mechanisms to ensure that the build process is both portable and performant.

Jenkins Configuration Paradigms for Maven

Before executing a migration, it is necessary to understand the three common patterns used in Jenkins to manage Maven projects. Each of these patterns represents a different way of interacting with the shell agent.

The first method is the Freestyle project with shell execution. In this scenario, the Jenkins administrator configures a build step that directly calls the mvn command from the shell. This assumes that the Jenkins agent is a persistent machine with Maven already installed in the system path.

The second method involves the Freestyle project using the Maven task plugin. This plugin provides a specialized wrapper for calling Maven goals, offering a more structured interface than a raw shell script. However, it still maintains a strict dependency on the host agent having the Maven binaries installed and configured.

The third and most common modern method is the Declarative Pipeline. This is defined using a Jenkinsfile stored within the Git repository, which allows the pipeline definition to evolve alongside the source code. A typical declarative pipeline for Maven utilizes a tools block to specify the required versions of Maven and the JDK.

For example, a standard Jenkinsfile might be structured as follows:

groovy pipeline { agent any tools { maven 'maven-3.6.3' jdk 'jdk11' } stages { stage('Build') { steps { sh "mvn package -DskipTests" } } stage('Test') { steps { sh "mvn test" } } stage('Install') { steps { sh "mvn install -DskipTests" } } } }

In this pipeline, the agent any directive tells Jenkins to run the job on any available agent. The tools section ensures that Maven 3.6.3 and JDK 11 are available in the environment. The stages are logically separated into Build, Test, and Install, mirroring the standard Maven lifecycle.

The Architecture of the .gitlab-ci.yml Migration

The migration to GitLab CI/CD involves translating the Jenkins stages into a YAML-based configuration. This process requires a fundamental understanding of how GitLab structures its execution flow. A pipeline consists of stages, and each stage contains one or more jobs.

To mimic the Jenkins behavior, the .gitlab-ci.yml file defines three specific stages: build, test, and install. These stages are executed in the order they are defined. The jobs assigned to these stages are build-JAR, test-code, and install-JAR.

Environmental Prerequisites and Runner Configuration

The successful execution of a Maven pipeline in GitLab requires specific infrastructure. Depending on the chosen approach, the requirements vary:

• Shell Executor: If using a GitLab Runner with a Shell executor, the runner must have Maven 3.6.3 and Java 11 JDK installed directly on the host machine. This is the closest equivalent to the persistent Jenkins agent.
• Docker Executor: For a more modern approach, the pipeline uses a Docker image. This removes the need for pre-installed software on the runner, as the environment is provisioned on-the-fly.

Detailed Analysis of the GitLab CI/CD Configuration

A comprehensive Maven configuration in GitLab CI/CD utilizes global keywords to ensure consistency across all jobs. The following table breaks down the key components used in the migration.

Global Variables and Maven Optimization

In a GitLab environment, configuring Maven requires specific variables to handle security and dependency storage.

The MAVEN_OPTS variable is critical for the stability of the build. Specifically, the setting -Dhttps.protocols=TLSv1.2 ensures that all HTTP requests made by Maven during the dependency resolution phase use TLS 1.2, which is required for secure communication with many modern artifact repositories.

Furthermore, the local Maven repository location must be explicitly managed. By setting -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository, the pipeline forces Maven to store its downloaded dependencies within the GitLab project directory. This is essential because the default Maven repository is usually located in the user's home directory, which is not persisted across different jobs or runners. By moving the repository into the project directory, GitLab's caching mechanism can effectively track and save the .m2/ directory.

The MAVEN_CLI_OPTS variable is used to pass arguments directly to the mvn command. In this migration example, -DskipTests is used. This allows the package and install jobs to execute without triggering the test suite, as the tests are already handled by a dedicated test-code job.

Implementing the Cache Mechanism

One of the most significant improvements over a basic Jenkins shell script is the use of the cache keyword. In Maven builds, downloading the entire set of dependencies for every single job is inefficient and slow.

The cache is configured using a key and paths. The key is set to $CI_COMMIT_REF_SLUG, which is a predefined GitLab variable representing a shortened version of the Git commit reference. This means that any job running on the same branch or commit will reuse the same cache archive. The paths section specifies .m2/, which tells the GitLab Runner to upload the contents of the local Maven repository to the cache server at the end of a job and download it at the start of the next.

Step-by-Step Job Execution Flow

The migrated pipeline consists of three distinct jobs, each mapped to a stage.

1. The test-code job: This job is assigned to the test stage. Its sole purpose is to execute mvn test. This ensures that the code is functionally correct before any attempt is made to package it.
2. The build-JAR job: This job is assigned to the build stage. It executes mvn $MAVEN_CLI_OPTS package. Because $MAVEN_CLI_OPTS contains -DskipTests, the build happens quickly without re-running the tests already validated in the previous stage.
3. The install-JAR job: This job is assigned to the install stage. It executes mvn $MAVEN_CLI_OPTS install. This command installs the compiled executable into the local .m2 repository, making it available for other potential processes within the environment.

The full configuration for a containerized Maven build is as follows:

```yaml
stages:
- build
- test
- install

default:
image: maven:3.6.3-openjdk-11
cache:
key: $CICOMMITREF_SLUG
paths:
- .m2/

variables:
MAVENOPTS: >-
-Dhttps.protocols=TLSv1.2
-Dmaven.repo.local=$CIPROJECTDIR/.m2/repository
MAVENCLI_OPTS: >-
-DskipTests

build-JAR:
stage: build
script:
- mvn $MAVENCLIOPTS package

test-code:
stage: test
script:
- mvn test

install-JAR:
stage: install
script:
- mvn $MAVENCLIOPTS install
```

Advanced Considerations for Simple Java Projects

For developers working on extremely simple Java projects—such as a "Hello World" application without a full Maven structure—the approach differs. In these cases, a full Maven lifecycle may be overkill.

A simple Java project might use a direct call to the Java compiler (javac). In a .gitlab-ci.yml file, this would appear as a script command:

yaml script: - /usr/lib/jvm/java-8-openjdk-amd64/bin/javac HelloWorld.java

However, as a project grows, the transition to Maven is strongly recommended. Moving from a single-file compilation to a Maven-based project allows the developer to leverage dependency management, standardized build lifecycles, and easier integration with CI/CD pipelines. The migration path from a "simple Java project" to a "Maven project" involves introducing a pom.xml file, which then allows the use of the comprehensive .gitlab-ci.yml configuration described in the previous sections.

Comparative Analysis: Jenkins vs. GitLab CI/CD

The migration from Jenkins to GitLab CI/CD is not just a change in syntax, but a change in philosophy.

• Agent Management: Jenkins often relies on persistent agents that require manual maintenance of the Java and Maven installations. GitLab CI/CD encourages the use of Docker images (e.g., maven:3.6.3-openjdk-11), which ensures that every build starts from a clean, known state, eliminating "it works on my machine" issues.
• Configuration Storage: While Jenkins can use a Jenkinsfile, many legacy projects still use the Jenkins UI for "Freestyle" configurations. GitLab mandates that the pipeline be defined as code in the .gitlab-ci.yml file, which provides a better audit trail and allows for version-controlled infrastructure.
• Caching Strategy: Jenkins relies on the persistent disk of the agent for the .m2 repository. GitLab uses a distributed cache system, allowing jobs to run on any available runner in a cluster while still sharing the same set of dependencies via the $CI_COMMIT_REF_SLUG key.
• Execution Flow: Both systems support stages and jobs. However, GitLab's integration of the pipeline directly into the Merge Request (MR) flow provides more immediate feedback to the developer compared to the separate build triggers often found in Jenkins.

Conclusion

The process of migrating a Maven build from Jenkins to GitLab CI/CD transforms a manual, agent-dependent process into a streamlined, containerized pipeline. By utilizing the default keyword to define a standard Maven Docker image and implementing a strategic caching mechanism for the .m2 directory, organizations can achieve faster build times and higher reliability. The use of global variables such as MAVEN_OPTS and MAVEN_CLI_OPTS allows for precise control over the build environment, ensuring security through TLS 1.2 and efficiency by skipping redundant tests. Whether starting from a simple "Hello World" Java file or a complex enterprise application, the transition to a .gitlab-ci.yml framework provides the scalability and reproducibility required for modern software development.

Sources

1. Migrate a Maven build from Jenkins to GitLab CI/CD
2. Configuring gitlab-ci.yml for simple java project