cacheport

Ecosystem · JVM

Maven repository cache for CI

Maven already knows how to use a mirror. Add one entry to settings.xml and every artifact, plugin and POM comes through Cacheport, from Maven Central or any other repository your build declares.

CP-MAVENManifest
Upstream
Maven Central, plus repositories you add
Endpoint
https://acme.cacheport.cc/maven/
Config
<mirror> in settings.xml
Credentials
${env.CACHEPORT_TOKEN} in <server>
Snapshots
Passed through, never cached long-term
Releases
Cached forever, immutable

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.

What gets cached
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)

.mvn/settings.xml
<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

.mvn/maven.config
--settings=.mvn/settings.xml
--batch-mode

The <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

.github/workflows/ci.yml
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 verify

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
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.

Questions

Does it replace Nexus or Artifactory?

For caching public artifacts, yes. If you also publish internal artifacts, keep your repository manager and add it as an upstream.

Does it cache plugins?

Yes. Plugins are artifacts like any other and go through the same mirror.

Can I deploy through Cacheport?

No. Cacheport is read-only for Maven. Deploy to your own repository as before.

Other ecosystems people set up next

Start on the free plan

20 GB of cache, every registry, unlimited users. Upgrade when your pipelines outgrow it.