skip to content

How do you initially generate Gradle's verification-metadata.xml file, and what does the --write-verification-metadata flag actually do during the build?

level: middleimportance: must knowfreq 55%

answer

  1. --write-verification-metadata sha256
  2. generative, never fails on mismatch
  3. records only resolved artifacts
  4. run broad task set for completeness
  5. commit gradle/verification-metadata.xml

basics

~10 s

Run the build with --write-verification-metadata <checksums>, e.g. ./gradlew build --write-verification-metadata sha256. Gradle resolves all dependencies and writes their computed checksums into gradle/verification-metadata.xml.

solid answer

~40 s

Dependency verification is bootstrapped by running any task that triggers resolution together with `--write-verification-metadata sha256` (you can list several algorithms, e.g. `sha256,pgp`). Gradle resolves every dependency and plugin in the invoked configurations, computes the requested checksums for each artifact (and its metadata file), and writes them into `gradle/verification-metadata.xml`. The flag is generative, not enforcing — it does NOT fail on mismatch; it records what it sees. Because it only captures artifacts actually resolved by the tasks you ran, you should invoke a broad set of tasks (build, plus things like testClasses, or `help` with extra configurations) so the file is complete. Once the file exists, subsequent normal builds enforce it. You commit the file to VCS so the whole team and CI verify against the same trusted set.

code

bash · 4 lines
bash
# Bootstrap with sha256 (and pgp); run a broad task set for completeness
./gradlew build testClasses --write-verification-metadata pgp,sha256

# Result is written to gradle/verification-metadata.xml — review the diff, then commit it

go deeper

for a junior

Know the command --write-verification-metadata sha256 generates gradle/verification-metadata.xml and that you commit it.

for a middle

Explain that the flag is generative-not-enforcing, lists algorithms, records artifact + metadata checksums, and only captures resolved artifacts — so run a broad task set.

for a senior

Discuss completeness strategy across multi-project builds and configurations, choosing sha256 vs pgp,sha256, and reviewing the diff as a trust decision before committing.

for a principal

Frame it as supply-chain governance: when/how the org adopts verification, the human review process for trust changes, and CI gating around the committed file.

## What dependency verification is Gradle's dependency verification is a supply-chain security feature: it pins every resolved artifact (and its metadata `.pom`/`.module` files) to a known checksum and/or PGP signature, recorded in `gradle/verification-metadata.xml`. After the file exists, any build that resolves a dependency whose bytes don't match the recorded trust is **failed before the artifact is used**, defending against compromised mirrors, typosquatting, and tampered caches. ## Bootstrapping with --write-verification-metadata You don't hand-write the file. You let Gradle generate it: ```bash ./gradlew build --write-verification-metadata sha256 ``` The flag takes a comma-separated list of what to record: checksum algorithms (`md5`, `sha1`, `sha256`, `sha512`) and/or `pgp`. During this run Gradle: 1. Resolves all dependencies/plugins pulled in by the tasks you invoked. 2. Computes the requested checksums for each artifact AND its metadata files. 3. **Writes** them into `gradle/verification-metadata.xml`, creating the file if absent or adding new entries if present. Crucially this mode is **write-only** — it never fails on a mismatch, it just records reality. So you must trust your network/cache at generation time. ## Completeness depends on what you run Gradle only records artifacts it actually resolved. If a dependency is only used by a configuration your invoked tasks didn't touch, it won't be in the file, and a later build that does touch it will fail with "not in metadata". Best practice: invoke a broad set of tasks in one generation run, e.g. ```bash ./gradlew build testClasses --write-verification-metadata sha256 ``` or add `help` plus resolve extra configurations. For multi-project builds, run from the root so all subprojects contribute. ## After generation - Review the diff (you're committing trust!). - Commit `gradle/verification-metadata.xml` to VCS. - From then on, normal builds **enforce** it; only re-run the write flag when you intentionally add/upgrade dependencies. Prefer `sha256` over weaker `md5`/`sha1`. Use `pgp` (often `pgp,sha256`) when you want signature-based trust with checksum fallback.

  • Why might the generated file be incomplete, and how do you make it complete?
    It only records artifacts actually resolved by the tasks you ran. Configurations not touched (e.g. integration-test or a code-quality plugin's classpath) are missing. Run a broad task set in one generation pass — build, testClasses, plus resolving extra configurations — ideally from the root project.
  • Does --write-verification-metadata enforce anything during the same run?
    No. It is purely generative — it records the checksums/signatures of what it resolves and never fails on a mismatch. Enforcement happens on subsequent normal builds once the file exists.

saying these in an interview costs you the question

  • Claiming the write flag also verifies/fails on mismatch in the same run.
  • Recommending md5/sha1 as the default algorithm for security.
  • Forgetting that only resolved artifacts get recorded, then being surprised by 'not in metadata' failures later.

context

resolving links…