Gradle remote build cache setup

Declare the remote cache in settings.gradle.kts (Kotlin DSL) or settings.gradle (Groovy DSL), using your workspace token as the HTTP Basic password. The username is ignored - leave it empty:

// settings.gradle.kts (Kotlin DSL)
buildCache {
    remote<HttpBuildCache> {
        url = uri("https://remote.cachely.dev")
        isEnabled = !System.getenv("GRADLE_CACHE_TOKEN").isNullOrBlank()
        isPush = System.getenv("GRADLE_CACHE_PUSH") == "true"
        credentials {
            username = "" // unused; the token identifies you
            password = System.getenv("GRADLE_CACHE_TOKEN") // your Cachely token
        }
    }
}

// settings.gradle (Groovy DSL)
buildCache {
    remote(HttpBuildCache) {
        url = 'https://remote.cachely.dev'
        enabled = (System.getenv('GRADLE_CACHE_TOKEN') ?: '').trim() != ''
        push = System.getenv('GRADLE_CACHE_PUSH') == 'true'
        credentials {
            username = '' // unused; the token identifies you
            password = System.getenv('GRADLE_CACHE_TOKEN') // your Cachely token
        }
    }
}

Enable the build cache for every invocation in gradle.properties (or pass --build-cache per run):

# gradle.properties
org.gradle.caching=true

Then export the token before building - locally from your shell, in CI from your secret store:

export GRADLE_CACHE_TOKEN=<your-token>
gradle build

Verify with gradle build --info and look for tasks reported as FROM-CACHE.

Set GRADLE_CACHE_PUSH=true alongside a read-write token wherever you want trusted builds to populate the cache. If you trust the users and code in your pipeline, one read-write token keeps setup simple, including for trusted pull requests. You can also enable uploads on developer machines.

If users you do not trust can run the pipeline or change its build code, choose a read-only token for those builds and leave the flag unset or set to false. Read-only tokens still allow downloads; omit the token if a build should not access private outputs.

Cachely enforces the token scope even if a build changes the upload flag. Without a token, the configuration above disables the remote cache and builds locally. See tokens and access control for creating and rotating credentials.

The Gradle remote build cache guide covers how task output caching works and what makes a task cacheable. If stores are silently skipped, see troubleshooting.

For complete pipeline recipes, follow GitHub Actions, CircleCI, or Jenkins build cache setup.