Gradle Configuration Cache: Cut CI Build Times in Half
Meta description: Deep dive into Gradle’s configuration cache internals — task graph serialization, cache miss root causes, incompatible plugins, and a step-by-step migration strategy for Android and KMP projects.
Tags: kotlin android kmp cicd multiplatform
TL;DR
Gradle’s configuration cache serializes the entire task graph to disk, skipping the configuration phase on subsequent builds. In multi-module Android and KMP projects, this can cut CI build times by 40–60%. Most teams stall on migration because they don’t understand why cache misses happen. The rest of this post covers that: the mental model and a systematic workflow for fixing them.
What the configuration cache actually does
The configuration cache is not a build cache. The build cache stores task outputs. The configuration cache stores the task graph — the DAG of tasks, their inputs, and their wiring — so Gradle can skip the configuration phase entirely on subsequent invocations.
The Gradle build lifecycle has three phases:
- Initialization — which projects participate
- Configuration — evaluate
build.gradle.kts, construct the task graph - Execution — run tasks
Configuration is expensive. In a 50-module Android project, evaluating every build.gradle.kts can consume 15–30 seconds on every CI run. The configuration cache eliminates this by serializing the resolved task graph to .gradle/configuration-cache/ as a binary snapshot and replaying it when inputs haven’t changed.
Why cache misses happen: the three root causes
1. Undeclared inputs
If your build script reads an environment variable or system property without declaring it as an input, Gradle can’t track it. Any change invalidates the entire cache.
// BAD — undeclared input, causes cache miss on every CI run
val version = System.getenv("BUILD_NUMBER")
// GOOD — declared as a provider, properly tracked
val version = providers.environmentVariable("BUILD_NUMBER")
2. File system reads at configuration time
Reading files during configuration (not execution) is a classic footgun. Gradle cannot fingerprint what it doesn’t know about.
// BAD — reads file at configuration time
val props = File("local.properties").readText()
// GOOD — deferred to execution via ValueSource
abstract class LocalPropertiesSource : ValueSource<String, ValueSourceParameters.None> {
override fun obtain(): String = File("local.properties").readText()
}
val props = providers.of(LocalPropertiesSource::class) {}
3. Incompatible plugins
This is where most migrations stall. Third-party plugins that use Project references at execution time, mutate shared state, or use deprecated APIs will fail cache compatibility checks.
| Plugin category | Typical compatibility | Common fix |
|---|---|---|
| AGP (8.x+) | Full | Upgrade to 8.x |
| KGP (1.9+) | Full | Upgrade to 1.9+ |
| Custom in-house plugins | Variable | Refactor to use Provider APIs |
| Legacy annotation processors | Often incompatible | Migrate to KSP |
| Some publishing plugins | Partial | Pin version, file issue upstream |
The migration workflow
The most reliable path is incremental — never attempt a big-bang migration. I’ve watched teams flip the flag project-wide and spend weeks untangling the fallout.
Phase 1: establish a baseline with --warn
./gradlew assembleDebug --configuration-cache --configuration-cache-problems=warn
This runs with the cache enabled but treats problems as warnings, not failures. You’ll get an HTML report at build/reports/configuration-cache/. Open it. Every problem has a stack trace pointing to the exact line.
Phase 2: fix by category
Work through problems in this order: your code first, then plugins. Problems in your build scripts are cheap to fix. Waiting on upstream plugin fixes can take months.
// Replace direct Task references with lazy providers
// BAD
tasks.named("generateBuildConfig").get().outputs.files
// GOOD
tasks.named("generateBuildConfig").flatMap { it.outputs.files.elements }
Phase 3: fingerprinting debug for persistent misses
If the cache keeps missing after fixes, use verbose fingerprinting:
./gradlew assembleDebug --configuration-cache \
-Dorg.gradle.configuration-cache.internal.report-file-system-access=true
This surfaces every file access during configuration, giving you a precise list of violations the standard report missed.
Phase 4: lock it in CI
# .github/workflows/build.yml
- name: Build
run: ./gradlew assembleDebug --configuration-cache
env:
GRADLE_BUILD_ACTION_CACHE_DEBUG_ENABLED: true
Treat any configuration cache failure as a build failure. This prevents regressions from slipping in.
Build time improvements
These numbers come from profiling real multi-module Android projects — treat them as rough benchmarks, not guarantees:
| Project size | Config phase (before) | Config phase (after) | Total CI improvement |
|---|---|---|---|
| 20 modules | ~12s | ~1s | ~18% |
| 50 modules | ~28s | ~2s | ~35% |
| 100+ modules | ~60s+ | ~3s | ~50%+ |
Gains compound when you combine this with the build cache and remote cache (Develocity or GitHub Actions cache). The configuration cache eliminates the fixed cost per run; the build cache eliminates the incremental cost.
Where to start
-
Run
--configuration-cache-problems=warntoday. You get the HTML report without breaking your build. Spend one sprint triaging the output before touching any code. -
Migrate your internal plugins first. Replace
Projectreferences withProvider-based APIs. This unblocks the majority of cache misses without waiting on external dependencies. -
Enforce it in CI as a hard failure. Once you’ve cleared the initial migration, any cache-incompatible code should fail the build. Discipline now saves you from months of drift later.