skip to content

How does the `metadataSources { }` block on a repository control which metadata Gradle reads, and when would you change it?

level: middleimportance: should knowfreq 40%

answer

  1. metadataSources { } per repository
  2. gradleMetadata / mavenPom / artifact()
  3. ignoreGradleMetadataRedirection
  4. POM marker redirects to .module
  5. order = preference; first hit wins

basics

~10 s

Inside a repository's metadataSources { } block you list which descriptors Gradle should look for — gradleMetadata(), mavenPom(), ignoreGradleMetadataRedirection(), or artifact(). Gradle tries them in the order declared.

solid answer

~40 s

Each repository in Gradle has a `metadataSources { }` configuration that tells Gradle which metadata files to look for and in what order. For a `maven { }` repo the default is to look up the POM, and — because POMs published by Gradle carry a marker — to redirect to the `.module` Gradle Metadata if present. You can declare `gradleMetadata()`, `mavenPom()`, `ignoreGradleMetadataRedirection()`, and `artifact()` (resolve by artifact existence even with no metadata). You override this when, for example, a repo serves jars with no POM (`artifact()` only), or you want to force-ignore GMM and read only the POM for a misbehaving publisher. Order matters: Gradle uses the first source that yields metadata. Tightening sources also speeds resolution by avoiding pointless network probes.

code

kotlin · 16 lines
kotlin
repositories {
    maven {
        url = uri("https://jars.acme.com")
        // This server only hosts bare jars, no POMs:
        metadataSources {
            artifact()
        }
    }
    mavenCentral {
        // Force POM-only for a publisher with a broken .module:
        metadataSources {
            mavenPom()
            ignoreGradleMetadataRedirection()
        }
    }
}

go deeper

for a junior

Know the block exists and that it picks between POM, Gradle metadata, and artifact-only resolution.

for a middle

Name each source and a concrete reason to override defaults (POM-less repo, broken .module, perf).

for a senior

Explain the POM redirection marker, ordering semantics, and the resolution-performance trade-off.

for a principal

Standardize metadataSources policy across an org's repos (e.g. mirrors/proxies) and reason about supply-chain/perf implications.

## The block Every repository declaration accepts a `metadataSources { }` block that controls **which metadata descriptors Gradle attempts to fetch** for a component, and in which order: ```kotlin repositories { maven { url = uri("https://repo.acme.com/maven") metadataSources { gradleMetadata() // look for the .module file mavenPom() // look for the .pom file ignoreGradleMetadataRedirection()// don't follow the POM->module marker artifact() // accept a component if only the jar exists } } } ``` ## The sources - **`mavenPom()`** — fetch and parse the `.pom`. - **`gradleMetadata()`** — fetch and parse the `.module` Gradle Module Metadata. - **`ignoreGradleMetadataRedirection()`** — by default, Gradle-published POMs contain a marker comment telling Gradle a `.module` file exists; this redirects Gradle to GMM. This source disables following that marker, so Gradle treats the component as POM-only. - **`artifact()`** — resolve a component purely by checking that an artifact (jar) exists, even with **no** metadata file at all. Useful for ad-hoc/flat-dir style repos. ## Defaults - A `maven { }` repository defaults to `mavenPom()` plus following the GMM redirection marker. - An `ivy { }` repository defaults to `ivyDescriptor()` (+ redirection). - `flatDir { }` is `artifact()` only. ## When you change it 1. **POM-less repositories** — a server that only hosts jars: declare `metadataSources { artifact() }` so Gradle stops failing on missing POMs. 2. **Force POM-only** — a publisher ships a broken `.module`; `mavenPom()` + `ignoreGradleMetadataRedirection()` makes Gradle read only the POM. 3. **Performance** — narrowing sources avoids extra HTTP HEAD/GET probes per module, which adds up over large graphs. ## Order semantics Gradle tries sources **in the order you declare them** and uses the first that produces metadata. So put your preferred/authoritative source first.

  • What does ignoreGradleMetadataRedirection() actually disable?
    It stops Gradle from following the marker embedded in a Gradle-published POM that points to a sibling `.module` file, so the component is treated as POM-only.
  • Why might narrowing metadataSources improve performance?
    Fewer declared sources means fewer network probes per module; over a large dependency graph those redundant lookups add measurable resolution time.

saying these in an interview costs you the question

  • Thinking metadataSources controls credentials or content filtering — it only controls which descriptor formats are fetched.
  • Assuming declaration order doesn't matter — Gradle uses the first source that yields metadata.

context

resolving links…