maven-mirror / repository pull-through cache

This host proxies and caches artifacts from repo.maven.apache.org (Central). Point Maven or Gradle here to speed up dependency resolution and cut outbound traffic. Replace mirror.example.com below with this server's actual hostname.

01 — GLOBAL MAVEN CONFIG

Mirror block in settings.xml

Redirect all repository requests through the mirror by adding a <mirror> entry to your user-level settings, usually ~/.m2/settings.xml.

~/.m2/settings.xml

<settings>
  <mirrors>
    <mirror>
      <id>mirror</id>
      <mirrorOf>*</mirrorOf>
      <url>https://mirror.example.com/maven2</url>
    </mirror>
  </mirrors>
</settings>

<mirrorOf>*</mirrorOf> catches every configured repository. Narrow it to central if you only want Central requests mirrored.

02 — PER-PROJECT (RECOMMENDED)

Repository override in pom.xml

Scope the mirror to a single project and commit it, so every teammate and CI job resolves through the mirror automatically — no local settings.xml edits required.

pom.xml

<repositories>
  <repository>
    <id>mirror</id>
    <url>https://mirror.example.com/maven2</url>
  </repository>
</repositories>

This adds the mirror as an extra repository rather than replacing Central outright — use the settings.xml <mirror> approach if you need a strict, project-wide override.

03 — GRADLE

Repository block

build.gradle

repositories {
    maven { url 'https://mirror.example.com/maven2' }
}

build.gradle.kts

repositories {
    maven("https://mirror.example.com/maven2")
}

04 — CI/CD

Pass an alternate settings.xml

No repo pom.xml changes needed — point Maven at a pipeline-provided settings file.

shell

mvn -s ci-settings.xml -B verify

05 — VERIFY

Confirm builds are going through the mirror

shell

mvn help:effective-settings | grep -A2 mirror
curl -s https://mirror.example.com/maven2/ -o /dev/null -w "%{http_code}\n"

# resolve something and time it
time mvn dependency:get -Dartifact=com.google.guava:guava:33.0.0-jre

Check	Expected result
`mvn help:effective-settings`	Lists `mirror.example.com` under `<mirrors>`
`GET /maven2/`	`200` — mirror is reachable
First resolve of an artifact	Slower — cache miss, fetched from upstream and stored
Repeat resolve	Fast — served from local `~/.m2/repository` cache

06 — NOTES

Pull-through, not a full copy. This mirror caches artifacts and checksums as they're requested — it doesn't proactively sync the entire Central catalog. The first resolve of any given groupId:artifactId:version is still fetched from repo.maven.apache.org.

mvn deploy still goes straight to the real repository defined in your <distributionManagement> — this mirror only accelerates dependency resolution. SHA-1/SHA-256 checksum verification against the recorded artifact hash still applies regardless of which source served the bytes.