Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 41 ยท Releasing and Production

Release Workflows and Reproducible Builds

Automate Maven releases with the release and versions plugins, use CI-friendly ${revision} versions and make builds reproducible with outputTimestamp.

A release is more than running deploy. Someone has to drop -SNAPSHOT from the version, build and test that exact state, tag it in version control, publish it, and move the project on to the next development version. Done by hand this is error-prone, so Maven offers plugins and conventions to automate it.

This lesson compares the classic maven-release-plugin with simpler approaches, shows the versions-maven-plugin for bulk edits, explains CI-friendly versions with ${revision}, and introduces reproducible builds: the goal that building the same source twice produces byte-identical artifacts. The Maven commands are read-only here; two Java stand-ins model the version arithmetic and the reproducibility idea.

A release, step by step

Drop SNAPSHOT 1.5.0-SNAPSHOT becomes 1.5.0.
Tag Commit and tag v1.5.0.
Publish Build and deploy the tagged code.
Next version Set 1.5.1-SNAPSHOT and commit.
1 / 2

The release plugin

The maven-release-plugin implements the full sequence in two goals. release:prepare checks that nothing is uncommitted and that no dependency is a SNAPSHOT, then changes the version in all POMs, commits, tags, and bumps to the next snapshot with a second commit. release:perform checks out the tag into a clean folder and runs deploy there.

Terminal
mvn release:prepare -DreleaseVersion=1.5.0 -DdevelopmentVersion=1.5.1-SNAPSHOT
mvn release:perform
mvn release:rollback   # undo a prepare that was not performed yet

It needs an <scm> section so it can tag the right repository. The plugin works, and many long-lived projects use it, but it makes several commits on your branch, assumes a linear history and is slow for large multi-module builds. For this reason many teams now choose a lighter workflow.

The versions plugin

versions-maven-plugin edits and inspects versions without any release ceremony. It is the tool for bulk changes in a multi-module build:

Terminal
mvn versions:set -DnewVersion=1.5.0 -DgenerateBackupPoms=false
mvn versions:commit
mvn versions:display-dependency-updates
mvn versions:display-plugin-updates
mvn versions:use-latest-releases

versions:set rewrites the version of the project, its modules and references between them in one go. display-dependency-updates lists which of your dependencies have newer versions, a handy report before upgrades. A common scripted release is: versions:set to the release version, mvn deploy -Prelease, then git tag, then versions:set to the next snapshot.

CI-friendly versions with revision

Rewriting POMs for every build is awkward. Since Maven 3.5 you can declare the version through special properties, ${revision}, ${sha1} and ${changelist}, and set them from the command line instead:

XML
<project>
  <groupId>com.example</groupId>
  <artifactId>text-tools-parent</artifactId>
  <version>${revision}</version>
  <packaging>pom</packaging>

  <properties>
    <revision>1.5.0-SNAPSHOT</revision>
  </properties>
</project>

Developers just run mvn verify. A CI release job runs:

Terminal
mvn deploy -Drevision=1.5.0

and the tag, for example v1.5.0, becomes the single source of truth. No version-bump commits are needed. One catch: the installed or deployed POM still contains the literal text ${revision}, which consumers cannot resolve. The flatten-maven-plugin fixes this by writing a "flattened" POM with the real value before packaging:

XML
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>flatten-maven-plugin</artifactId>
  <configuration>
    <updatePomFile>true</updatePomFile>
    <flattenMode>resolveCiFriendliesOnly</flattenMode>
  </configuration>
  <executions>
    <execution>
      <id>flatten</id>
      <phase>process-resources</phase>
      <goals><goal>flatten</goal></goals>
    </execution>
  </executions>
</plugin>

Use the three properties exactly by those names, and only in <version> elements (the parent version reference and module versions included). Child modules then write <version>${revision}</version> in their <parent> block. Maven 4 supports this natively, so the flatten step may become unnecessary there.

Reproducible builds

A build is reproducible if two people compiling the same commit with the same tools get identical bytes. That lets anyone verify that a published jar really corresponds to the public source. Typical sources of differences are timestamps inside archives, the order of files, and local paths.

Maven's answer is a single property that fixes the timestamp of everything written into archives, and makes the archiving plugins sort entries:

XML
<properties>
  <project.build.outputTimestamp>2026-01-15T10:00:00Z</project.build.outputTimestamp>
</properties>

With a recent parent POM or plugin versions that honor it, the jar, source and javadoc plugins stamp every entry with that moment. The release plugin updates the property automatically; with ${revision} workflows you set it from the commit time, for example -Dproject.build.outputTimestamp=$(git log -1 --format=%cI). Verify the result with the reproducible-build plugin or by building twice and comparing checksums:

Terminal
mvn clean verify
sha256sum target/text-tools-1.5.0.jar
mvn clean verify
sha256sum target/text-tools-1.5.0.jar

Both hashes must match. If they do not, a plugin is still writing the current time or an unordered file list; upgrading plugin versions usually fixes it. Pin all plugin versions, as ranges break reproducibility on their own.

A software bill of materials

A bill of materials (SBOM) lists every component inside an artifact. The CycloneDX Maven plugin generates one during package from the resolved dependency tree, in a JSON or XML format that vulnerability scanners understand (see dependency security). Reproducible builds and SBOMs together answer two questions customers increasingly ask: "what is in it?" and "is it really built from that source?".

A version bumper

This stand-in implements the arithmetic a release script performs: parse a version, drop the SNAPSHOT suffix for the release, and compute the next development version for patch, minor or major bumps.

Java Release and next-development versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Each line corresponds to one step of release:prepare: choose the release version, the tag name and the next development version. A script using ${revision} needs only the second line.

A reproducibility demonstration

The second stand-in builds a small fake "jar" from file entries and computes its SHA-256 hash. When each entry carries the current time and the entries come in arbitrary order, two builds differ. When every entry gets a fixed timestamp and the entries are sorted, the hashes match. This is exactly the rule behind outputTimestamp, in miniature.

Java Same input, same hash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Real archives also record permissions, compression details and the JDK that wrote them, which is why reproducibility depends on plugin versions as well as the timestamp.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does mvn release:prepare do?

    prepare edits the versions, commits, tags and moves to the next development version. release:perform then builds and deploys the tag.
  2. 2. What is the advantage of <version>${revision}</version>?

    You pass -Drevision=1.5.0 in CI, so the tag decides the version. The flatten plugin writes the resolved value into the published POM.
  3. 3. Which property fixes timestamps for a reproducible Maven build?

    project.build.outputTimestamp tells archiving plugins to use one fixed time and to sort entries so output is deterministic.
  4. 4. Which command lists dependencies that have newer versions?

    The versions plugin reports available updates for dependencies; versions:display-plugin-updates does the same for plugins.

Summary

  • A release drops SNAPSHOT, builds and tests, tags, publishes and moves to the next snapshot.
  • release:prepare and release:perform automate that but make several commits; versions:set plus a script is lighter.
  • ${revision} with the flatten plugin lets CI choose the version, with no bump commits.
  • Set project.build.outputTimestamp and pin plugin versions for byte-identical, verifiable builds.
  • An SBOM from CycloneDX documents what an artifact contains.

Next, make the pipeline fast in Maven in CI and Faster Builds.