Gradle Remote Cache

Before configuring Gradle Remote Cache, ensure you can access your BuildFetch dashboard and create resources in your account. The setup flow is sequential: create an Org first, then a Project of type Gradle, then generate Project-scoped tokens.

Configuring BuildFetch cache for Gradle is extremely beneficial because it saves time CI, developers, and AI Agents spend rebuilding the same code. When a PR is merged to the main branch, its build results are ready for new builds to consume.

For CI, generate a Project token with cache:readwrite scope. Use this token in your CI environment so pipelines can both read cached artifacts and upload new ones.

For local development, generate cache:readonly token access as well. You can issue one shared token for all developers, or create one token per developer.

Individual cache:readwrite tokens can also be generated, but the user generating them must be a Project admin or an Org admin.

If your build setup is extremely deterministic, it can be beneficial to use developer tokens with cache:readwrite access.

Per-developer tokens are usually preferred because they provide better operational control and make it possible to revoke access for one developer without impacting the rest of the team.

See the official Gradle Build Cache documentation: https://docs.gradle.org/current/userguide/build_cache.html.

Gradle is extremely flexible in this regard. BuildFetch recommended way is to configure settings.gradle.kts like so:

buildCache {
    remote<HttpBuildCache> {
        // On CI it's easiest to provide Env Vars
        // On local macOS it's easier to provide ~/.gradle/gradle.properties for consistency between Terminal & IDE
        val remoteUrl: String? = "BUILDFETCH_GRADLE_REMOTE_CACHE_URL"
            .let { System.getenv(it) ?: providers.gradleProperty(it).orNull }

        val user: String? = "BUILDFETCH_GRADLE_REMOTE_CACHE_USER"
            .let { System.getenv(it) ?: providers.gradleProperty(it).orNull }

        val token: String? = "BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN"
            .let { System.getenv(it) ?: providers.gradleProperty(it).orNull }

        if (remoteUrl != null && user != null && token != null) {
            isEnabled = true

            url = uri(remoteUrl.trim())

            credentials {
                username = user.trim()
                password = token.trim()
            }

            isPush = System.getenv("ON_CI") == "true"
        } else {
            isEnabled = false
        }
    }
}

On CI, the environment variables need to be provided, for example:

export BUILDFETCH_GRADLE_REMOTE_CACHE_URL="xyz"
export BUILDFETCH_GRADLE_REMOTE_CACHE_USER="token-auth"
export BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN="..."

For Developer access, add values to ~/.gradle/gradle.properties:

BUILDFETCH_GRADLE_REMOTE_CACHE_URL=xyz
BUILDFETCH_GRADLE_REMOTE_CACHE_USER=token-auth
BUILDFETCH_GRADLE_REMOTE_CACHE_TOKEN=...