Transitioning Maven Build Lifecycle Architectures from Jenkins to GitLab CI/CD

The evolution of Continuous Integration and Continuous Deployment (CI/CD) architectures has necessitated a profound shift in how engineering teams manage dependency lifecycles, particularly within the Java ecosystem. As organizations move away from legacy Jenkins installations, the migration of Maven-based build processes to GitLab CI/CD represents more than a mere change in tooling; it is a fundamental reconfiguration of the build environment, dependency resolution logic, and artifact management strategies. Jenkins, traditionally relying on persistent agents and various plugin-driven methodologies—such as the Maven task plugin or declarative Jenkinsfiles—requires a paradigm shift when transitioning to GitLab's job-based, container-centric model. This transition involves moving from a stateful agent model to a highly scalable, stateless execution model where the environment is defined by code, often through Docker images, and dependencies are managed through sophisticated registry proxying and mirroring techniques.

Decoupling Build Logic from Jenkins Legacy Architectures

In a Jenkins-centric environment, Maven builds are frequently executed through one of three primary architectural patterns. Each pattern dictates how the build interacts with the underlying host and how the Maven lifecycle is triggered. Understanding these patterns is critical for ensuring that the logic is accurately translated into the GitLab CI/CD syntax.

The first pattern is the Freestyle project utilizing direct shell execution. In this scenario, the Jenkins agent acts as a simple wrapper, passing raw shell commands to the operating system. This method is highly imperative and relies heavily on the pre-installed state of the host machine. The second pattern involves the Maven task plugin. This is a more structured approach where Jenkins manages the Maven execution through a dedicated plugin, using a script wrapper to invoke Maven goals. This creates a layer of abstraction between the Jenkins UI and the command line, but it still maintains a tight coupling with the agent's installed Maven version. The third pattern is the modern standard: the Declarative Pipeline. This utilizes a Jenkinsfile to define the build lifecycle, often specifying specific tools like maven-3.6.3 and jdk11 within a tools block.

When migrating these to GitLab CI/CD, the distinction between these methods becomes secondary to the configuration of the GitLab Runner. Whether the original source was a shell script or a declarative pipeline, the target GitLab configuration can be unified into a consistent, stage-based pipeline.

Implementing GitLab CI/CD Pipelines for Maven Projects

The transition to GitLab CI/CD requires a redefinition of the build sequence into stages and jobs. In Maven, the lifecycle typically follows a sequence of testing, packaging, and installation. In GitLab, these are mapped to specific stages to ensure a logical and ordered execution flow.

There are two primary execution environments available via GitLab Runners: the Shell executor and the Docker executor. The choice between them significantly impacts the maintenance overhead and the portability of the build process.

The Shell Executor Approach

For teams migrating from Jenkins who wish to maintain a similar environment to their persistent Jenkins agents, the Shell executor is the closest functional equivalent. This requires a GitLab Runner with a Shell executor installed on a machine where Maven 3.6.3 and Java 11 JDK are already present.

The configuration in .gitlab-ci.yml for a Shell executor focuses on defining the stages and the specific commands to be executed. The following configuration mimics the standard Jenkins build, test, and install sequence:

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

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
```

In this configuration, the variables block is critical. Setting MAVEN_OPTS to include -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository ensures that the Maven local repository is contained within the project directory, which is essential for caching purposes in a CI environment.

The Docker Executor Approach

The Docker executor represents the modern, cloud-native standard for CI/CD. Unlike the Shell executor, which requires manual maintenance of the host machine's software versions, the Docker executor allows the pipeline to define its own environment using a container image. This removes the need for maintaining virtual machines and provides immense flexibility for expanding pipeline functionality.

The following configuration utilizes the default keyword to ensure all jobs run within a specific Maven and OpenJDK container:

```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
```

By using cache, the pipeline stores the .m2/ directory, keyed by the commit reference slug. This significantly accelerates subsequent builds by preventing the need to re-download the entire dependency tree every time a job runs.

Advanced Dependency Management via GitLab Maven Package Registry

A critical component of a mature DevOps pipeline is the ability to manage internal dependencies. GitLab provides a built-in Maven Package Registry that can act as both a destination for published artifacts and a proxy for external repositories.

Overriding Maven Central with GitLab Mirroring

By default, Maven queries Maven Central via the Super POM. In an enterprise environment, it is often necessary to redirect these requests to a private registry to ensure security, speed, and control. To ensure all package requests are sent to GitLab instead of Maven Central, a <mirror> section must be added to the settings.xml file.

The following XML configuration demonstrates how to proxy the central repository through GitLab:

xml <settings> <servers> <server> <id>central-proxy</id> <configuration> <httpHeaders> <property> <name>Private-Token</name> <value>&lt;personal_access_token&gt;</value> </property> </httpHeaders> </configuration> </server> </servers> <mirrors> <mirror> <id>central-proxy</id> <name>GitLab proxy of central repo</name> <url>https://gitlab.example.com/api/v4/projects/&lt;project_id&gt;/packages/maven</url> <mirrorOf>central</mirrorOf> </mirror> </mirrors> </settings>

Implementing this mirror has several technical implications:

• It centralizes dependency traffic through the GitLab instance.
• It allows the registry to proxy files, sending both the file and related checksums in a single request.
• It reduces the number of individual web requests required by Maven clients.
• It decreases the total load on the GitLab instance.
• It improves the overall execution time of client commands.

Note that if the GitLab instance uses object storage, the Maven package registry ignores the proxy download setting in the object storage configuration; instead, proxy download is always enabled for Maven package registry downloads.

Automating Package Creation in CI/CD

To automate the publishing of packages, a dedicated ci_settings.xml should be created. This file serves as the Maven settings file during the CI/CD process. It must include a server section with the exact same ID defined in the project's pom.xml.

When building new packages, the CI/CD pipeline can be configured to trigger a new package creation every time the default branch is updated. This facilitates continuous delivery of versioned releases, multi-module project support, and conditional publishing based on branch or tag logic.

Integration with Gradle and Alternative Build Tools

While the primary focus is often Maven, GitLab's package registry is equally capable of supporting Gradle projects. The integration involves configuring the repositories block in the build.gradle file and managing credentials through a properties file.

To authenticate with the GitLab Maven group repository in Gradle, follow these steps:

1. Create a gradle.properties file in the GRADLE_USER_HOME directory.
2. Add the following line to the properties file:
   • gitLabPrivateToken=REPLACE_WITH_YOUR_TOKEN

Depending on the DSL used in the project, the repository configuration will differ:

For Groovy DSL:

groovy repositories { maven { url "https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven" name "GitLab" credentials(PasswordCredentials) { username = 'REPLACE_WITH_NAME' password = gitLabPrivateToken } authentication { basic(BasicAuthentication) } } }

For Kotlin DSL:

kotlin repositories { maven { url = uri("https://gitlab.example.com/api/v4/groups/<group>/-/packages/maven") name = "GitLab" credentials(BasicAuthentication::class) { username = "REPLACE_WITH_NAME" password = findProperty("gitLabPrivateToken") as String } } }

In these configurations, the CI_JOB_TOKEN can also be used as a substitute for a personal access token in certain automated environments, providing a more secure, short-lived credential for authentication.

Technical Analysis of Registry Performance and Storage

The performance of the Maven package registry is heavily influenced by how checksums and files are delivered to the client. The registry's ability to proxy files and bundle them with checksums in a single request is a key optimization. This reduces the latency inherent in the traditional Maven "request-response" cycle where a client might make multiple trips to a server to verify a single dependency.

However, architects must be aware of the storage implications. When using object storage (such as AWS S3 or similar), there is a specific technical constraint where the registry ignores the proxy download setting in the object storage configuration. This means that proxy download is always enabled for Maven package registry downloads in these environments. For organizations not utilizing object storage, this behavior is a non-issue and does not impact instance performance.

The ability to integrate these packages with code quality and security scans within the GitLab pipeline allows for a holistic approach to the software supply chain. By combining versioned releases with automated security checks, organizations can ensure that every Maven package published to the registry meets the required compliance and stability standards.

Sources

1. Migrate a Maven build from Jenkins to GitLab CI/CD
2. Maven Repository in GitLab