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.
- 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
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
org.gradle.caching=trueOnly 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
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 buildMore for GitHub Actions: GitHub Actions setup guide.
GitLab CI
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.