axion-release-plugin: Gradle versions derived from SCM tags

A version in the build file is a version that drifts

The problem axion-release-plugin attacks is familiar to anyone who has shipped a Gradle project. Maven came with the maven-release-plugin, which did the awkward work of versioning a release for you. Gradle has no equivalent, and the README argues it probably does not need one, because the way software engineering moved on is to treat version control as the ultimate source of truth about the project version. The consequence of the old way is that the version gets hardcoded in pom.xml or build.gradle, which means there are two places to keep in step: the build file and the tag. Every release becomes a small manual ritual of editing a file, tagging, and hoping the two agree. This plugin takes the other position. Instead of reading the project version from the build file, it derives it from the nearest tag in SCM, and falls back to a default when nothing has been tagged. The audience is teams that tag their releases in Git already and want the build to agree with the tag automatically.

A tagged commit is a release, anything after it is a snapshot

The rule is short enough to state in one sentence and precise enough to explain most of the plugin's behaviour. If the current commit is a tagged commit, the project has a release version. If there were any commits after the last tag, the project is in a SNAPSHOT version. Nothing else is consulted, and nothing needs to be configured for this to work, which is the appeal. A developer on a feature branch therefore gets a SNAPSHOT, a build server building the tagged commit gets a release version, and the two never disagree because neither of them states a version anywhere. Combined with Semantic Versioning rules, the README argues this makes project versions much easier to manage alongside SCM tag versions. The interesting part is what the plugin does with the existing tag when you release again. The session transcript in the README shows that after a tagged commit, a new commit and another release, two tags exist, v0.1.0 and v0.1.1, and the reported current version is the newer one.

Comparing this with the Maven release plugin

The alternative to this plugin is not another Gradle plugin, it is the way Maven already works, and the README draws the contrast directly. The maven-release-plugin did all the dirty work of a release for Maven projects. Gradle has no such tool, and the plugin's author argues Gradle probably does not need a tool that rewrites build files, because the philosophy of source control as the source of truth makes that rewriting unnecessary. The practical difference in approach is therefore not about features, it is about where the state lives. A Maven-style release flow treats the build file as the thing that is edited and promoted, and the tag as a record of what happened. Axion treats the tag as the decision and the build file as a pure consumer of it. For a project that has been migrated from Maven to Gradle, or for a team that has been bitten by a build file and a tag disagreeing, that difference is the entire value proposition. For a team that needs the version to be something other than a tag, such as a CI build counter, the model does not fit.

Applying the plugin and reading scmVersion

The basic usage is a plugin block and a version assignment, and the version in the example is the one the README pins, 1.21.2:

plugins {
    id("pl.allegro.tech.build.axion-release") version "1.21.2"
}

version = scmVersion.version

The plugin identifier is pl.allegro.tech.build.axion-release, which is also the identifier used on the Gradle Plugin Portal, while the Maven Central artifact is pl.allegro.tech.build:axion-release-plugin. The property scmVersion is the handle the build uses to query the derived version, and assigning its version field to the project version is what wires the two together. The project is written in Groovy and the example is in Kotlin, which is the usual Gradle split between the plugin implementation and the DSL that consumers write. The requirements are stated plainly above the example: JDK 17 or newer and Gradle 7.6 or newer. Nothing else in the snippet is required, which is the sign of a plugin that is trying to be invisible in the build file rather than to impose a structure on it.

currentVersion and release in a plain shell session

The README shows the whole lifecycle in a terminal transcript, and it is the clearest evidence of how the plugin behaves. The first state is a repository with no tags at all:

$ git tag
<empty list>

$ ./gradlew currentVersion
0.1.0-branch-SNAPSHOT

$ ./gradlew release

With nothing tagged, the fallback version is used and the project reports itself as a SNAPSHOT, with the branch name folded into the version string. The release task then creates the first tag, v0.1.0, and the current version becomes 0.1.0:

$ git tag
v0.1.0

$ ./gradlew cV
0.1.0

$ git add -A && git commit -m "Updates something" && ./gradlew release

That last part matters. The tag is not created by the plugin alone in isolation, the transcript shows a commit going in first and the release task running afterwards, and after it two tags exist:

$ git tag
v0.1.0
v0.1.1

$ ./gradlew cV
0.1.1

The current version follows the newest tag. The cV spelling is an alias for currentVersion, and the transcript shows a commit going in and the release task running afterwards, before the second tag appears.

The repository holds the plugin, the docs and the build for the docs

The tree shows a project that ships its documentation as a first-class artefact. There is a src/ directory for the plugin itself, a build.gradle.kts and settings.gradle.kts for the build, and a gradle wrapper. Documentation lives in docs/ with a mkdocs.yml at the root and a readthedocs.yml, and the requirements.txt pins the documentation toolchain exactly, mkdocs at 1.6.1 and the mkdocs-material theme at 9.7.7. That pinning is a small but telling detail: the docs site is built in CI from a fixed toolchain, so a documentation build does not break because a theme released a new version. There is a DOCS_README.md and a DEVELOPMENT.md for contributors, a docker/ directory, a jitpack.yml for building from JitPack, and a codecov.yml for coverage reporting. The published documentation lives at axion-release-plugin.readthedocs.io. Continuous integration is a GitHub Actions workflow named ci.yml. The plugin itself is published to Maven Central and to the Gradle Plugin Portal, and the README links the readthedocs site for the full reference, which is where the details of prefix handling and configuration live.

Requirements, licence and the release cadence

Two hard floors apply before anything else: JDK 17 or newer, and Gradle 7.6 or newer. A build on an older Gradle will not run the plugin, which matters for teams still on a long-term support line. The licence is Apache License 2.0, which is permissive and carries the standard patent grant, so the plugin can be used in commercial builds subject to keeping the licence notice. The release history shows steady maintenance: v1.21.4 on 2026-09-17, v1.21.3 on 2026-08-05 and v1.21.2 on 2026-06-03, with the last push to the repository on 2026-10-19. The version numbers are in the low twenties for a one-decimal scheme, which tells you the plugin is mature rather than experimental. One thing to watch is that the README example still pins the plugin at 1.21.2 while the newest published release is v1.21.4, so copying the snippet gives you a slightly older version than the current one, and the plugin version in the build file is the kind of string a shared convention plugin can automate. The README does not document how to override the derived version for a build that is not tied to a tag, and it says nothing about migrating an existing project that already has a hardcoded version, so both of those are questions for the documentation site rather than for the README.

Editorial conclusion

axion-release-plugin suits Gradle teams that already tag in Git and are tired of a version property drifting from the tags, since the release task and the currentVersion task keep the two in step. It is the wrong tool if the version is derived from something other than SCM, for example a build number baked in by a CI system, and the README does not document a way to override that. Before adopting it, check the JDK 17 and Gradle 7.6 floors against the build, and pick the plugin version deliberately, because the snippet in the README still pins 1.21.2 while the newest published release is v1.21.4.

Frequently asked questions

Official sources

1. allegro/axion-release-plugin on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases