Validate the Gradle Distribution SHA-256 Checksum

Set distributionSha256Sum in gradle-wrapper.properties to verify the integrity of the downloaded Gradle distribution.

Explanation

Always set the distributionSha256Sum property in your gradle-wrapper.properties file to verify the integrity of the downloaded Gradle distribution. This ensures the gradle-X.X-bin.zip file matches the official SHA-256 checksum published by Gradle, protecting your build from corruption or tampering.

distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
distributionSha256Sum=2b3f4...sha256-here...f4511

This validation step enhances security by preventing the execution of compromised or incomplete Gradle distributions.

The official SHA-256 checksums can be found on the Gradle releases page.

References

Tags

#properties, #wrapper

Validate the Gradle Wrapper on every Upgrade

The Gradle Wrapper runs before your build logic and can deeply affect your build. You should treat any change to the Wrapper as security-sensitive.

Validate the Wrapper JAR and distribution settings every time you upgrade Gradle.

Explanation

When you update Gradle, two Wrapper files typically change:

  • gradle/wrapper/gradle-wrapper.jar

  • gradle/wrapper/gradle-wrapper.properties (distributionUrl and optionally distributionSha256Sum)

You should verify that:

  • The Wrapper JAR is the official binary published by Gradle (not tampered with).

  • The Wrapper JAR checksum matches one of the values published at gradle.org/release-checksums.

  • The distribution URL points to the expected Gradle release.

  • The distribution checksum (if configured via distributionSha256Sum) matches the release you intend to use (also listed on gradle.org/release-checksums).

Running an unverified Wrapper risks executing untrusted code before any of your build’s safeguards run.

Do this

If you use GitHub Actions, you can use the Gradle Wrapper validation action.

This action validates the checksum of every gradle-wrapper.jar in your repository and fails the build if it finds any unknown JAR:

github/workflows/gradle-wrapper-validation.yml
name: Validate Gradle Wrapper
on:
  pull_request:
    paths:
      - 'gradlew'
      - 'gradlew.bat'
      - 'gradle/wrapper/**'

jobs:
  wrapper-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Recommended action (new namespace)
      - name: Verify Gradle Wrapper
        uses: gradle/actions/wrapper-validation@v3

References

Tags

#wrapper