cacheport

Ecosystem · JVM

Gradle dependency and build cache for CI

Gradle has two kinds of cache worth sharing: downloaded dependencies and task outputs. Cacheport covers both, with repository mirrors for Maven Central and the Plugin Portal and an HTTP remote build cache.

CP-GRADLEManifest
Dependencies
https://acme.cacheport.cc/maven/
Plugins
https://acme.cacheport.cc/gradle-plugins/
Build cache
https://acme.cacheport.cc/gradle-cache/
Config
settings.gradle.kts
Protocol
Maven repository layout, HTTP build cache
Releases
Cached forever, immutable

How Gradle caching works

Declaring repositories in settings.gradle.kts with FAIL_ON_PROJECT_REPOS makes every module resolve through Cacheport and stops individual build files from adding their own repositories.

The remote build cache stores task outputs keyed by their inputs. When a CI job compiles code that another job already compiled with identical inputs, Gradle downloads the result instead of doing the work.

What gets cached
Dependencies
From Maven Central, Google Maven and repositories you add.
Plugins
From the Gradle Plugin Portal.
Task outputs
In the remote build cache, evicted least-recently-used.

Set it up

settings.gradle.kts

settings.gradle.kts
pluginManagement {
    repositories {
        maven {
            url = uri("https://acme.cacheport.cc/gradle-plugins/")
            credentials { username = "ci"; password = System.getenv("CACHEPORT_TOKEN") }
        }
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven {
            url = uri("https://acme.cacheport.cc/maven/")
            credentials { username = "ci"; password = System.getenv("CACHEPORT_TOKEN") }
        }
    }
}

buildCache {
    remote<HttpBuildCache> {
        url = uri("https://acme.cacheport.cc/gradle-cache/")
        isPush = System.getenv("CI") != null
        credentials { username = "ci"; password = System.getenv("CACHEPORT_TOKEN") }
    }
}

Turn the build cache on

gradle.properties
org.gradle.caching=true

Only CI pushes to the remote build cache in this setup; laptops read from it. That keeps the cache filled with outputs from clean, reproducible environments.

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
      - uses: gradle/actions/setup-gradle@v4
      - run: ./gradlew build

More for GitHub Actions: GitHub Actions setup guide.

GitLab CI

.gitlab-ci.yml
build:
  image: eclipse-temurin:21
  variables:
    GRADLE_USER_HOME: $CI_PROJECT_DIR/.gradle-home
  script:
    - ./gradlew build
  cache:
    key: gradle
    paths: [.gradle-home/wrapper]

More for GitLab CI: GitLab CI setup guide.

Build cache sizing

Build cache entries are evicted least-recently-used once your plan's build cache quota is full. Entries are small and change often, so a few gigabytes usually hold the outputs of every active branch. See Build Cache for limits and hit-rate reporting.

Troubleshooting

Errors that usually mean the public registry is the bottleneck, and what Cacheport changes about them.

Questions

Does the Gradle wrapper download go through Cacheport?

The wrapper downloads the Gradle distribution from services.gradle.org. Cache it with your CI provider's cache or with setup-gradle.

Is the build cache safe to share between branches?

Yes. Entries are keyed by task inputs, so a branch only gets outputs that match its own inputs exactly.

Does it work with Android builds?

Yes. Add Google's Maven repository as an upstream and Android Gradle Plugin dependencies are cached too.

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.