Build caches
Groundbox is a remote build cache for 5 build tools: Turborepo, Gradle, sccache, Bazel and Nx. A task one build ran is not run again by the next one that has the same inputs, whether that build is a CI job, a sandbox, a laptop or an agent. One store per team, kept on the same machines as your runners.
On Groundbox runners: nothing to set
Every job on a Groundbox runner already points these tools at the cache on its machine, with no key:
- Turborepo:
TURBO_API,TURBO_TEAMandTURBO_TOKENare set.turbo runuses it. - sccache:
SCCACHE_BUCKET,SCCACHE_ENDPOINTand the rest of its S3 settings are set. SetRUSTC_WRAPPER=sccacheas usual. - Gradle: an init script makes the box the remote cache of any build that turns the build cache on and names no remote cache of its own. Turn it on in
gradle.properties:
org.gradle.caching=true- Bazel:
/etc/bazel.bazelrcsets--remote_cache. Your project's.bazelrccomes after it and wins. - Nx: not on by default, since a workspace on Nx Cloud would change caches. One step turns it on:
- name: Nx remote cache on the box
run: echo "NX_SELF_HOSTED_REMOTE_CACHE_SERVER=$GROUNDBOX_NX_CACHE_URL" >> "$GITHUB_ENV"Your workflow's own env wins over any of these: set TURBO_API to keep another remote cache, or GROUNDBOX_GRADLE_CACHE=off for Gradle.
In sandboxes: off until you turn it on
A sandbox does not use the cache unless it asks, so a build in it runs in full and never restores another sandbox's or a CI job's results. Set GROUNDBOX_BUILD_CACHE=on in the sandbox's env, or in its template's, and its commands get the same Turborepo and sccache settings as a runner, the Gradle init script, and GROUNDBOX_BAZEL_CACHE_URL and GROUNDBOX_NX_CACHE_URL for Bazel's --remote_cache and Nx. The sandbox's own env wins over them.
groundbox sandbox create --env GROUNDBOX_BUILD_CACHE=onFrom laptops and other CI
Use https://api.groundbox.dev/build-cache with an API key from API keys that has cache:read, and cache:write to save.
Turborepo
export TURBO_API=https://api.groundbox.dev/build-cache
export TURBO_TEAM=groundbox
export TURBO_TOKEN=gbx_... # a key with cache:read (cache:write to save)
turbo run buildGradle
// settings.gradle.kts: the box's cache on Groundbox runners, api.groundbox.dev/build-cache anywhere else
buildCache {
remote<HttpBuildCache> {
val onBox = System.getenv("GROUNDBOX_GRADLE_CACHE_URL")
url = uri(onBox ?: "https://api.groundbox.dev/build-cache/gradle/")
isPush = true
if (onBox == null) {
credentials {
username = "groundbox"
password = System.getenv("GROUNDBOX_CACHE_KEY")
}
} else {
isAllowInsecureProtocol = true
}
}
}Put the key in GROUNDBOX_CACHE_KEY. Keep org.gradle.caching=true in gradle.properties.
sccache
export RUSTC_WRAPPER=sccache
export SCCACHE_BUCKET=groundbox
export SCCACHE_ENDPOINT=https://api.groundbox.dev/build-cache/s3
export SCCACHE_REGION=auto
export AWS_ACCESS_KEY_ID=gbx_... # the key goes here; the signature is not checked
export AWS_SECRET_ACCESS_KEY=unusedBazel
# user.bazelrc or ~/.bazelrc (not committed: it holds the key)
build --remote_cache=https://api.groundbox.dev/build-cache/bazel
build --remote_header=Authorization=Bearer gbx_...Nx
export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://api.groundbox.dev/build-cache/nx
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=gbx_...Who can save what
- Builds of a repository's default branch, and API keys with cache:write, save to your team's shared cache. Everyone in the team restores from it.
- Pull requests and other branches save to a cache of their own, and restore from it, then the shared one. Code in a pull request can never put an entry where a default-branch build will restore it.
- To let pull requests from your own repositories save to the shared cache, turn it on in settings. A pull request from a fork never does.
- Sandboxes that turn the cache on save to a sandbox cache and restore from it, then the shared one. Other sandboxes neither save nor restore.
- Caches are never shared between teams.
Limits
A team keeps 5 GB on the free plan and 50 GB on the $20 plan. Past that, the entries used longest ago go first; saving never fails for room. One entry is at most 5 GB. From outside, an upload is at most 32 MB; a larger entry is not saved and the build goes on.
Hits and misses
The Caches page shows what the cache holds and its hit rate per tool over the last week, with the build time Turborepo says its hits saved. groundbox cache stats prints the same.