How Maven caching works
A mirror with <mirrorOf>*</mirrorOf> catches requests for every repository Maven knows about. Maven sends them to Cacheport, which fetches from Maven Central or the matching upstream on the first request and serves from cache afterwards.
Release artifacts in Maven repositories are immutable by convention, so Cacheport keeps them permanently. Metadata files such as maven-metadata.xml are refreshed every few minutes so version ranges and plugin prefixes resolve correctly.
- Release artifacts
- JARs, POMs, sources and checksums, cached forever.
- maven-metadata.xml
- Refreshed every 5 minutes for version ranges and plugin prefixes.
- Snapshots
- Passed through to the upstream so builds see the newest snapshot.
Set it up
.mvn/settings.xml (commit this, it has no secrets)
<settings>
<mirrors>
<mirror>
<id>cacheport</id>
<mirrorOf>*</mirrorOf>
<url>https://acme.cacheport.cc/maven/</url>
</mirror>
</mirrors>
<servers>
<server>
<id>cacheport</id>
<username>ci</username>
<password>${env.CACHEPORT_TOKEN}</password>
</server>
</servers>
</settings>Use it on every build
--settings=.mvn/settings.xml
--batch-modeThe <server> id must match the mirror id. Maven reads the token from the environment, and .mvn/maven.config makes every mvn call in the project use these settings.
Use it in CI
Store the token as a secret named CACHEPORT_TOKEN, then pick your provider.
GitHub Actions
jobs:
build:
runs-on: ubuntu-latest
env:
CACHEPORT_TOKEN: ${{ secrets.CACHEPORT_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 21
cache: maven
- run: mvn verifyMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
build:
image: maven:3.9-eclipse-temurin-21
script:
- mvn verify
cache:
key: maven
paths: [.m2/repository]
variables:
MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"More for GitLab CI: GitLab CI setup guide.
Repositories declared in POMs
Some dependencies declare their own repositories in a POM. With mirrorOf *, Maven sends those requests to Cacheport too. Add the repository as an upstream in your workspace so Cacheport knows where to fetch from; requests for unknown repositories return a clear error instead of silently going around the cache.
Troubleshooting
Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.