Pin distributionSha256Sum in gradle/wrapper/gradle-wrapper.properties, and check the wrapper JAR against Gradle's published checksums or signature. The wrapper is a binary committed to your repository that runs on developer and CI machines, so a swapped copy is a quiet way into your build.
Definitions
The Gradle wrapper is a small script plus a JAR that downloads and runs a specific Gradle version. The distribution is the Gradle ZIP it downloads. Two things can be tampered with: the downloaded distribution and the committed wrapper JAR.
Step 1: pin the distribution checksum
Add the SHA-256 of the distribution ZIP to gradle-wrapper.properties as distributionSha256Sum. You can generate it with the wrapper task:
./gradlew wrapper --gradle-version 9.8.1 --gradle-distribution-sha256-sum <hash>
Take the hash from the .sha256 file beside the distribution on services.gradle.org or from Gradle's release checksums page. The version above is an example. Use your own.
Two things from the docs to remember. Verification only runs if the configured distribution has not been downloaded yet, so a cached copy skips it. And the wrapper task fails if the properties file has a sum but the task configuration does not, though the sum is kept when the Gradle version does not change.
Step 2: validate the wrapper JAR
The JAR is a binary in your repository. Options:
| Method | How |
|---|---|
| GitHub Actions | The Setup Gradle action validates it automatically, built in since v4 |
| Checksum | Compute SHA-256 with sha256sum, or Get-FileHash on Windows, and compare with the published list |
| Signature | Verify the .asc signature with gpg |
If the hash does not match, first check whether it matches a different Gradle version. If the JAR's version differs from your properties file, rerun the wrapper task. If the hash is not listed at all, the docs say to treat the JAR as untrustworthy and report it to security@gradle.com.
Step 2b: automate the check
A manual check gets forgotten. Put the wrapper validation in CI so every pull request that touches the wrapper files runs it. With GitHub Actions, the Setup Gradle action does this for you. On other systems, add a small job that computes the SHA-256 of the JAR, compares it with the value you expect, and fails when it differs.
Step 3: guard changes in review
Changes to gradle-wrapper.jar and gradle-wrapper.properties should need a named reviewer. A wrapper JAR change in a pull request that claims to fix a typo is a reason to stop and look.
Why this belongs in a supply chain checklist
Your dependencies get most of the attention. The build tooling runs with the same access and often with CI secrets. Verifying it costs minutes. For verifying the libraries themselves, see Gradle dependency verification.
Quick check
Does the checksum protect me if the distribution is already cached?
No. The docs say verification only happens if the distribution has not been downloaded yet.
Where do I find the correct hash?
On the .sha256 file next to the distribution on services.gradle.org, or on the Gradle release checksums page.
Sources
Last reviewed: 19 October 2026.
