Enhancing Version Management in MuleSoft CI/CD with Maven

This article aims to provide effective strategies for version management when building MuleSoft APIs. It’s important to note that MuleSoft APIs utilize Maven, which is more than just a build tool — it serves as a comprehensive project management solution. Maven automates the build process, manages dependencies, and supports tasks such as running tests and generating reports. Proper setup of the primary Maven file, the POM file, is crucial for maintaining control over the API lifecycle. A key aspect of this lifecycle management is version control, especially within a Continuous Integration/Continuous Deployment (CI/CD) pipeline.

So, let’s dive in and start learning!

Version Management: Importance

Version management is crucial in a CI/CD pipeline for several reasons:

• Release Management: Defines and manages different versions, simplifying release planning and execution.
• Rollback Capabilities: Enables quick reversion to stable versions, minimizing downtime and disruptions.
• Consistency: Ensures each environment uses the correct application version, reducing discrepancies and deployment errors.
• Compliance and Auditing: Maintains change records and version histories, aiding compliance with industry standards.

Effective version management leads to a stable development lifecycle, higher-quality releases, and improved efficiency.

Version Management: Maven Tools

One of the key features that make Maven so powerful is its plugin system. Maven plugins provide all the useful functionalities required to execute and manage the project build. Each plugin is a collection of goals that execute specific tasks during the build process.

In the context of version management for MuleSoft APIs, Maven offers several powerful plugins to streamline the process.

Two key plugins that stand out for their capabilities in controlling version management are:

• maven-release-plugin
• build-helper-maven-plugin
• versions-maven-plugin

Maven Release Plugin

The Maven Release Plugin is primarily used to prepare and perform the release of a project with Maven, significantly reducing repetitive, manual tasks.

Here’s a structured overview of its core functions:

🎿 prepare

1. Check uncommitted changes: Check that there are no uncommitted changes in the sources.
2. Update to Release Version: Converts the project version in the POM file from SNAPSHOT to a full release number.
3. Run Tests: Executes the project’s test suite.
4. Commit Changes: Commits the updated POM file to Source Control Management (SCM).
5. Create Release Tag: Creates a release tag in SCM.
6. Update to Next SNAPSHOT Version: Changes the version in the POM file to the next SNAPSHOT version.
7. Commit Changes: Commits the new SNAPSHOT version to SCM.

⛷️ perform

1. Checkout and Deploy: Checks out the release tag from SCM and deploys the release.

In this article, we are not focusing on the perform phase as it doesn’t affect version management. We will concentrate solely on the prepare phase. To prepare the release, include the following in your POM file:

1️⃣ Add the scm section with a developerConnection URL pointing to your SCM system:

<project>
  <scm>
    <developerConnection>scm:git:https://github.com/my-org/my-project.git</developerConnection>
  </scm>
</project>

2️⃣ Add the Maven Release Plugin with a specific version:

<project>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>3.0.1</version>
      </plugin>
    </plugins>
  </build>
</project>

Run maven command:

mvn release:prepare 

You will see that the version of the project has changed from 1.0.0-SNAPSHOT to 1.0.1-SNAPSHOT in the pom.xml file and the Release tag has been created in your SCM.

While the plugin automates version management, it limits the developer’s full control over the process. Ensure you are comfortable with this level of automation before integrating it into your workflow.

Build Helper Maven Plugin

The build-helper-maven-plugin is a Maven plugin that has a wide range of goals. It helps in attaching additional artifacts to be installed and deployed, adding custom source directories, and creating directories. However, in the context of version management, we will be interested in the parse-version goal of the build-helper-maven-plugin. It helps to access the component parts of a version string by parsing it.

After the goal is executed following properties will be accessible for use:

parsedVersion.majorVersion
parsedVersion.minorVersion
parsedVersion.incrementalVersion
parsedVersion.qualifier
parsedVersion.buildNumber

Apart from the above properties, the following properties will be set:

parsedVersion.nextMajorVersion
parsedVersion.nextMinorVersion
parsedVersion.nextIncrementalVersion
parsedVersion.nextBuildNumber

Let’s dive into the details of how it works.

First, we need to add the plugin to the pom.xml file of the Mulesoft API. It should be placed within the <build> section under <plugins>:

 <build>
  <plugins>
   ...
   <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>build-helper-maven-plugin</artifactId>
       <version>3.6.0</version>
       <executions>
         <execution>
           <id>parse-version</id>
           <goals>
             <goal>parse-version</goal>
           </goals>
         </execution>
       </executions>
   </plugin>
  </plugins>
 </build>

To validate that everything is working correctly, the antrun plugin can echo out properties:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-antrun-plugin</artifactId>
            <version>1.1</version>
            <executions>
                <execution>
                    <phase>validate</phase>
                    <goals>
                        <goal>run</goal>
                    </goals>
                    <configuration>
                        <tasks>
                            <echo>Major: ${parsedVersion.majorVersion}</echo>
                            <echo>Minor: ${parsedVersion.minorVersion}</echo>
                            <echo>Incremental: ${parsedVersion.incrementalVersion}</echo>
                            <echo>Qualifier: ${parsedVersion.qualifier}</echo>
                            <echo>Next major: ${parsedVersion.nextMajorVersion}</echo>
                            <echo>Next minor: ${parsedVersion.nextMinorVersion}</echo>
                            <echo>Next incremental: ${parsedVersion.nextIncrementalVersion}</echo>
                        </tasks>
                    </configuration>
                </execution>
            </executions>
    </plugin>

Run the following command from the command prompt:

mvn clean install

You should now see that the plugin is working and has correctly parsed the project’s version.

The build-helper-maven-plugin's parse-version goal is perfect for projects that require breaking down the version number and accessing its individual components when building a manifest file.

However, parsing the version is not enough; we also need control over setting and updating it. For this purpose, we will use another plugin, the versions-maven-plugin, which we will discuss next.

Versions Maven Plugin

The Versions Plugin is primarily used to manage the versions of artifacts in a project’s POM. It allows you to update, set, and verify the versions of your project’s dependencies, plugins, and even the project itself. This can help ensure compatibility and consistency across your project’s components.

To start using the plugin, we need to add it to the <plugins> section of the pom.xml file:

<plugins>
  ...
  <plugin>
     <groupId>org.codehaus.mojo</groupId>
     <artifactId>versions-maven-plugin</artifactId>
     <version>2.8.1</version>
  </plugin>
  ...
</plugins>

Once added, you can utilize various goals provided by the Versions Plugin to manage your project’s versioning effectively. While the plugin offers a wide range of goals, we will focus specifically on the goal related to updating and setting the project version: the set goal. This goal has a range of parameters that can be used to manipulate the project's version. After setting and updating the version, we always need to use the commit goal to commit the changes.

Let’s explore the most practical and useful parameters of the set goal:

1️⃣ removeSnapshot: This parameter determines whether to remove -SNAPSHOT from the existing version.

To execute, run from the bash:

mvn versions:set -DremoveSnapshot versions:commit

Here are the results demonstrated in the screenshot below. The plugin successfully found and removed SNAPSHOT from the project.version property, updating the pom.xml.

2️⃣ nextSnapshot: This parameter specifies whether to increment the version number and add -SNAPSHOT to the existing version. Unless specified by nextSnapshotIndexToIncrement, it will increment the last minor index of the snapshot version (e.g., the z in x.y.z-SNAPSHOT).

To execute, run from the bash:

mvn versions:set -DnextSnapshot versions:commit

The result can be seen in the logs in the screenshot below. The plugin found the project’s version, incremented it, and added -SNAPSHOT to it.

3️⃣ newVersion: This parameter sets the new version number. It is especially convenient to use with the build-helper-maven-plugin's parse-version goal. In practice, it looks like this:

mvn build-helper:parse-version versions:set \
 -DnewVersion=\${parsedVersion.majorVersion}.\${parsedVersion.nextMinorVersion}.\${parsedVersion.nextIncrementalVersion}-SNAPSHOT \
 versions:commit 

The result is displayed in the logs in the screenshot below. The plugin detected the project’s version and applied the specified rules from the newVersion property to generate the new version.

Versions maven plugin allows to manipulate your project’s version effectively and ensure that changes are committed properly.

Effective version management is crucial for successful API development and deployment, as well as for CI/CD processes. It ensures smooth transitions between versions, maintaining stability, and meeting compliance standards. With the tools and strategies outlined in this article, you are well-equipped to manage your MuleSoft API versions efficiently.

Simply add the commands to your CI/CD pipeline, and you’ll have the power of version control at your fingertips.

I’d love to hear your thoughts!

Resources and useful links:

1. Apache Maven Wiki
2. Apache Maven official
3. Maven Release Plugin
4. Build Helper Maven Plugin
5. Mvn Repo: Build Helper Maven Plugin
6. Build Helper Maven Plugin: Parse Version
7. Versions Plugin
8. Versions:Set