gradle wrapper: Pin the Gradle Version
gradle wrapper writes the gradlew scripts and gradle-wrapper.properties so every machine, including CI, runs the exact same Gradle version.
The wrapper task is what you run once to (re)generate or upgrade the wrapper. CI should always invoke ./gradlew, never a system Gradle, so the version is pinned.
What it does
The wrapper task generates gradlew, gradlew.bat, and gradle/wrapper/gradle-wrapper.properties. --gradle-version sets the version that the properties file points at, so the next ./gradlew invocation downloads and uses exactly that build.
Common usage
./gradlew wrapper --gradle-version 8.7
./gradlew wrapper --gradle-version 8.7 --distribution-type all
# verify integrity by pinning the distribution checksum
./gradlew wrapper --gradle-version 8.7 --gradle-distribution-sha256-sum <sha>Flags
| Flag | What it does |
|---|---|
| --gradle-version <v> | Gradle version the wrapper will use |
| --distribution-type bin|all | "all" includes sources/docs for IDE |
| --gradle-distribution-sha256-sum <sha> | Pin the distribution checksum for verification |
| --gradle-distribution-url <url> | Use a custom distribution mirror |
In CI
Commit the wrapper files and run ./gradlew so the build is reproducible regardless of the runner image. Cache ~/.gradle/wrapper so the distribution is downloaded once. Pinning the sha256 sum protects against a tampered mirror.
Common errors in CI
"Verification of Gradle distribution failed!" with "Expected checksum ... but was ..." means the downloaded distribution did not match the pinned sum (corruption or a wrong URL). "Could not install Gradle distribution from '...'" is a network/proxy failure reaching services.gradle.org. "ERROR: JAVA_HOME is not set" means no JDK on the runner before the wrapper even runs.