Gradle turns on dependency verification when gradle/verification-metadata.xml exists. You generate it with one command, but the generated file trusts whatever your repositories serve today. Treat it as a draft: review it, mark entries you checked, commit it, and review every later change to it like code.
Generate the baseline
From the Gradle documentation:
./gradlew --write-verification-metadata sha256
To add PGP signatures as well:
./gradlew --write-verification-metadata sha256,pgp
To preview without touching your file, run with help and dry run. Gradle writes verification-metadata.dryrun.xml instead:
./gradlew --write-verification-metadata sha256 help --dry-run
Bootstrapping is incremental, so rerunning adds entries and keeps the existing ones.
The caveat that matters
The docs warn that the generated file trusts what is currently in your repositories. If a bad artifact is already there, you just recorded its checksum as good. Gradle marks generated entries with origin Generated by Gradle. After you verify an entry, change the origin to Verified. That gives reviewers a way to see which entries a human has checked.
What it checks
- Artifacts such as JARs and ZIPs.
- Metadata files: POMs, Ivy descriptors and Gradle Module Metadata. This can be turned off, which reduces security.
- Project and settings plugins.
It does not verify SNAPSHOT versions or artifacts built locally.
Failure modes
The default mode is strict, which fails as early as possible. Lenient reports errors without failing, and off ignores verification. You set it with the dependency-verification flag, for example ./gradlew --dependency-verification lenient build.
A missing entry fails with a message that the checksum is missing from verification metadata. Add the entry or rerun bootstrapping. A checksum mismatch means the artifact may have been tampered with, so investigate before editing the file. The docs mention a stale local cache as one possible cause.
For CI logs, set org.gradle.dependency.verification.console=verbose in gradle.properties. Otherwise Gradle writes an HTML report.
Signatures
Gradle supports ASCII armored PGP signatures on remote repositories. Enable them with verify-signatures set to true in the configuration block. Signatures are not trusted by default: add the full 40 character fingerprint to trusted-keys. If an artifact has no signature, Gradle falls back to its checksum, so keep checksums too.
Commit it and review diffs
The documentation is written around reviewing diffs in version control. Commit the file. In a pull request that changes a dependency, the diff to the verification file should match exactly what you expect. For related ideas, see what the npm lockfile integrity field protects.
Safeguard dependency and SBOM scanning can list the artifacts a Gradle build resolves and flag known vulnerabilities. You can try a free scan at gold.safeguard.sh/scan.
Quick check
Is the generated file proof the artifacts are safe?
No. It records what your repositories served at that moment. Review it before you trust it.
Which command refreshes missing keys right away?
Run ./gradlew build --refresh-keys. Cached missing keys otherwise last 24 hours.
Sources
Last reviewed: 19 October 2026.
