Run Gradle once with the write-verification-metadata option to generate gradle/verification-metadata.xml, commit it, and Gradle will check every downloaded artifact against it on each build. A mismatch fails the build. Checksums prove an artifact did not change. Signatures add proof of who published it.
What it protects against
Gradle's documentation frames the risk plainly: if an attacker replaces a library in a repository with a malicious file that has the same coordinates, your next build downloads it without warning. Dependency verification closes that gap by comparing what you download to what you recorded.
The same page is just as clear about the limit. Verification is meant to protect you from compromised dependencies, not to stop you including vulnerable ones. You still need scanning for that.
Step by step
- From the project root, generate a baseline. The documentation shows the command with sha256 for checksums only, or sha256,pgp to include signatures.
./gradlew --write-verification-metadata sha256 help
- Preview first if you want. Adding a dry-run flag writes verification-metadata.dryrun.xml instead of changing the real file. The documentation notes dry run misses any resolution that happens at task execution time.
- Review the generated file in your diff. Every component, artifact and checksum is there in a version control friendly XML file.
- Commit it. Verification turns on automatically as soon as the file exists at gradle/verification-metadata.xml.
- Run a normal build to confirm it passes.
Checksums or signatures
| Method | Proves | Weak spot |
|---|---|---|
| Checksum | The file contents did not change | Says nothing about who produced it |
| Signature | Who published the artifact | Signatures can use weak hashes, and the key must be trusted |
| Both | Integrity and provenance | More metadata to maintain |
Gradle supports MD5, SHA1, SHA-256 and SHA-512, but its guide says only SHA-256 and SHA-512 are considered secure for modern use.
Settings worth knowing
The verification file is global. One file covers the root project, subprojects and buildSrc. For included builds, the current build's file wins.
Gradle has three modes: strict (the default), lenient and off. A common pattern is to keep strict in CI and relax locally during a heavy upgrade, using the dependency-verification flag or property. Treat lenient as a temporary state.
IDEs often download javadoc and sources, which would fail verification. The documentation shows a trusted-artifacts block with regular expressions to trust those files only.
Keep it healthy
When you upgrade a dependency, new entries are needed. Gradle's failure message tells you the missing group, name and version. Add entries through the same generate command and review the diff like any other code change. A reviewer who skims a checksum change is the weak link, so ask that dependency bumps and metadata changes land in the same pull request.
Try it yourself
Click through it at your own pace, or open it full screen. Notice how many transitive components a normal project pulls in. Each one is an entry your verification file has to cover.
Safeguard can add the other half of the picture: dependency scanning and SBOM generation for Gradle projects, plus policy gates on pull requests. A free scan is at gold.safeguard.sh/scan.
Quick check
Does Gradle dependency verification find vulnerable libraries?
No. It detects tampered or unexpected artifacts. A library with a known CVE will pass verification if its checksum matches. Use a vulnerability scanner alongside it.
Is the verification file safe to commit?
Yes, it is designed for version control. It holds checksums and trusted key IDs, not secrets.
Sources
Last reviewed: 19 October 2026.
