@@ -37,7 +37,13 @@ apply plugin: 'open-java-format.release-conventions'
 
 // GitHub Actions sets GITHUB_REF_TYPE=tag on a tag build; otherwise derive the
 // version from git history (needs a full clone: actions/checkout fetch-depth: 0).
-version System.env.GITHUB_REF_TYPE == 'tag' ? System.env.GITHUB_REF_NAME : gitVersion()
+//
+// Read through providers rather than System.env: the configuration cache tracks a provider as an input
+// and invalidates when it changes, while a plain System.env read is invisible to it — a cached
+// configuration then keeps handing out the version of whichever environment happened to fill it.
+def refType = providers.environmentVariable('GITHUB_REF_TYPE')
+def refName = providers.environmentVariable('GITHUB_REF_NAME')
+version refType.getOrElse('') == 'tag' ? refName.get() : gitVersion()
 
 // The GraalVM image is built by its own per-platform CI job, never as a side effect of
 // `./gradlew build`: an aggregate build must not require a GraalVM toolchain on a machine that
 
@@ -17,3 +17,11 @@ palantir.native.formatter=true
 # unpacking a downloaded JDK does not preserve the symlink GraalVM ships at bin/native-image.
 org.gradle.java.installations.auto-download=false
 org.gradle.java.installations.fromEnv=JDK21_HOME,GRAALVM_HOME
+
+# Configuration cache off for now: parts of this build are not cache-safe yet — the GraalVM plugin
+# cannot serialise its NativeConfigurations bean (see README, phase 1) — and chasing a stale entry
+# costs more than the cache saves. Turn it on for a single run with --configuration-cache.
+#
+# A gradle.properties in GRADLE_USER_HOME outranks this file, so anyone who turns the cache on
+# globally keeps it on here too.
+org.gradle.configuration-cache=false
@@ -39,14 +39,21 @@ def embeddedLibs = configurations.runtimeClasspath.filter { file ->
 
 // Generated, not written in MANIFEST.MF, where it sat at 2.38.0 and never followed the build. OSGi
 // takes three numbers and an optional [A-Za-z0-9_-] qualifier, so a `git describe` version such as
-// 2.97.0-41-gf6667a2.dirty has to be reshaped into 2.97.0.41-gf6667a2-dirty.
+// 2.97.0-41-gf6667a2.dirty is reshaped into 2.97.0.41-gf6667a2-dirty.
+//
+// Every checkout has to yield something valid, never an exception: a branch build has no tag to
+// describe from — on CI's shallow clone the version is a bare commit hash — and throwing here failed
+// the evaluation of this project, taking every task in the build down with it. A version that does not
+// start with three numbers becomes the qualifier of 0.0.0 instead.
 def osgiVersion = {
-    def matcher = (project.version.toString() =~ /^(\d+)\.(\d+)\.(\d+)[.-]?(.*)$/)
+    def raw = project.version.toString()
+    def sanitize = { String text -> text.replaceAll(/[^A-Za-z0-9_-]/, '-') }
+    def matcher = (raw =~ /^(\d+)\.(\d+)\.(\d+)[.-]?(.*)$/)
     if (!matcher.find()) {
-        throw new GradleException("Cannot derive an OSGi Bundle-Version from '${project.version}'")
+        return "0.0.0.${sanitize(raw)}"
     }
     def release = "${matcher.group(1)}.${matcher.group(2)}.${matcher.group(3)}"
-    def qualifier = matcher.group(4).replaceAll(/[^A-Za-z0-9_-]/, '-')
+    def qualifier = sanitize(matcher.group(4))
     qualifier.isEmpty() ? release : "${release}.${qualifier}"
 }()