mvn release:prepare: Usage & Common CI Errors
Tag a release: set the version, commit, tag, then bump to next SNAPSHOT.
release:prepare is a goal of the maven-release-plugin that prepares a release in source control: it removes the -SNAPSHOT suffix, commits and tags the release version, then increments to the next development SNAPSHOT and commits again. release:perform then builds and deploys from the tag.
What it does
release:prepare runs a dry-run build, rewrites the POM version, creates an SCM tag, and pushes two commits (release + next SNAPSHOT). It records state in release.properties so a failed run can be resumed or rolled back with release:rollback.
Common usage
mvn release:prepare
mvn release:prepare -DdryRun=true # rehearse without committing
mvn release:prepare -Dresume=false # ignore prior release.properties
mvn release:perform # build + deploy from the tag
mvn release:rollback # undo a prepareCommon error in CI (and the fix)
Symptom: "Unable to commit files ... You don’t have permission" or "fatal: could not read Username" / "remote: Authentication failed" during the tag push. Cause: the CI checkout uses a read-only or detached credential that cannot push tags. Fix: give the build a token with write/contents permission, configure git to use it (or set <scmCommentPrefix> and an authenticated <developerConnection> URL), and ensure the checkout is on a branch, not a detached HEAD.
Using this in CI
- Set the shell explicitly and enable
set -euo pipefail; the default runner shell does not stop on the first error inside a multi-line block. - Pin the tool version. An unpinned build tool turns a runner image update into a build break on unchanged code.
- Prefer non-interactive and batch flags. Progress output designed for a terminal bloats CI logs and can hang without a TTY.
- Write machine-readable output (JSON, JUnit) to a file and upload it as an artifact, so a failure is diagnosable without re-running the job.