skip to content

What is the verification-metadata.xml file in Gradle, where does it live, and what is its purpose?

level: juniorimportance: must knowfreq 55%

answer

  1. gradle/verification-metadata.xml
  2. presence = enabled
  3. one shared file per build
  4. <configuration> + <components>
  5. checksums and/or signatures

basics

~10 s

It's an XML file at gradle/verification-metadata.xml that lists trusted checksums and/or signatures for every dependency and plugin Gradle resolves. When present and enabled, Gradle verifies each artifact against it before use.

solid answer

~40 s

`gradle/verification-metadata.xml` is Gradle's dependency-verification manifest. It lives in the `gradle/` directory next to the wrapper, so it's committed once and shared across the whole build (root and all subprojects). Its job is supply-chain integrity: it records the expected checksums and/or PGP signatures of every artifact (jars, POMs, plugin marker files, even the wrapper-resolved dependencies) the build downloads. Once the file exists, Gradle automatically switches verification **on**; on each resolution it recomputes the artifact's checksum and compares it to the recorded value, failing the build on any mismatch or any unlisted artifact. The top-level `<configuration>` block holds global switches (`verify-metadata`, `verify-signatures`) and trust rules; `<components>` holds the per-artifact expectations. Because it's a single shared file, a tampered or swapped dependency anywhere in the dependency graph is caught.

code

xml · 17 lines
xml
<?xml version="1.0" encoding="UTF-8"?>
<verification-metadata>
   <configuration>
      <verify-metadata>true</verify-metadata>
      <verify-signatures>false</verify-signatures>
   </configuration>
   <components>
      <component group="org.apache.commons" name="commons-lang3" version="3.14.0">
         <artifact name="commons-lang3-3.14.0.jar">
            <sha256 value="..."/>
         </artifact>
         <artifact name="commons-lang3-3.14.0.pom">
            <sha256 value="..."/>
         </artifact>
      </component>
   </components>
</verification-metadata>

go deeper

for a junior

Know it's an XML file under gradle/ that lists trusted checksums and turning it on is automatic when the file exists.

for a middle

Explain the two top-level blocks (<configuration>, <components>) and that the file is shared across the whole build.

for a senior

Frame it as supply-chain integrity: single reviewable source of truth covering transitive deps and plugin artifacts; activation by presence; per-invocation overrides.

for a principal

Discuss governance — mandating the file across repos, code-review of changes to it, and the trust model it encodes for the org.

## What problem it solves When Gradle resolves dependencies it downloads jars and POMs from remote repositories (Maven Central, plugin portals, internal Nexus, etc.). Without verification, a compromised repository, a man-in-the-middle, or a typo-squatted coordinate could feed your build a malicious artifact. **Dependency verification** lets you pin the exact bytes you trust, so any deviation fails the build. The pinned expectations live in one file: `gradle/verification-metadata.xml`. ## Location and scope The file lives at `gradle/verification-metadata.xml`, relative to the **root** of the build, alongside `gradle/wrapper/`. There is exactly one such file per build — it is **not** per-subproject. It applies to every configuration that resolves dependencies in the root and all included subprojects, and also to the artifacts Gradle itself needs (plugins, their marker POMs, etc.). ## Activation is implicit There is no `enabled="true"` attribute. The mere **presence** of the file turns verification on. To disable it for a single invocation you pass `--dependency-verification off` (or `lenient`); to remove it entirely you delete the file. ## High-level structure ```xml <?xml version="1.0" encoding="UTF-8"?> <verification-metadata> <configuration> <verify-metadata>true</verify-metadata> <verify-signatures>false</verify-signatures> </configuration> <components> <component group="com.google.guava" name="guava" version="32.1.3-jre"> <artifact name="guava-32.1.3-jre.jar"> <sha256 value="..."/> </artifact> </component> </components> </verification-metadata> ``` The two children of the root element are: - **`<configuration>`** — global behaviour: which verifications run (`verify-metadata`, `verify-signatures`), key-server configuration, and `<trusted-artifacts>` / `<trusted-keys>` exemptions. - **`<components>`** — one `<component>` per group:name:version, each containing one or more `<artifact>` entries (the jar, the `.module`, the `.pom`) carrying the trusted `<sha256>`, `<sha512>`, or `<pgp>` values. ## Why one shared file matters Because every resolution across the build consults the same file, an attacker who swaps a transitive dependency three levels deep is still caught — the recomputed checksum won't match the pinned one. This is the file's core value: a single, reviewable, version-controlled source of truth for exactly which bytes the build is allowed to consume.

  • How do you turn verification off for a single build without deleting the file?
    Pass `--dependency-verification off` (skip entirely) or `--dependency-verification lenient` (warn instead of fail) on the command line.
  • Does each subproject get its own verification-metadata.xml?
    No. There is one file at `gradle/verification-metadata.xml` for the whole build; it covers the root and all subprojects.

saying these in an interview costs you the question

  • Claiming there is an `enabled` flag — activation is by file presence, not an attribute.
  • Saying it lives in `build.gradle` or per-module — it's a single file under `gradle/`.

context

resolving links…