What the agent does
The agent reads the build before it flips the switch, because the configuration cache fails the build on the first incompatible line and the fix depends on which plugin wrote it. In a project laid out like spring-projects/spring-petclinic, gradle/wrapper/gradle-wrapper.properties pins Gradle 9.5.1 and there is no gradle.properties at all. build.gradle applies java, checkstyle, org.springframework.boot 4.1.0, io.spring.dependency-management 1.1.7, org.graalvm.buildtools.native 1.1.2, org.cyclonedx.bom 3.2.4, io.spring.javaformat 0.0.47 and io.spring.nohttp 0.0.11, sets a Java 17 toolchain, configures the cyclonedxDirectBom task to depend on compileJava, points checkstyle and checkstyleNohttp at src/checkstyle, wires formatMain and formatTest after the checkstyle tasks, and disables the AOT variants of the checkstyle and format tasks with enabled = false. Its second line is different in kind: gradle.startParameter.excludedTaskNames += ["checkFormatAot", "checkFormatAotTest"] edits the invocation's own parameters from inside the build script, for two tasks the script also disables further down. settings.gradle only names the root project. The test tree under src/test/java has Testcontainers-backed MySqlIntegrationTests and PostgresIntegrationTests, PetClinicIntegrationTests, and controller tests under owner, vet and system. .github/workflows/gradle-build.yml sets up JDK 17 with cache: maven, runs gradle/actions/setup-gradle@v4 and then ./gradlew build; the Maven workflow beside it runs ./mvnw -B verify and is untouched by this change.
The first run is a measurement. The agent runs ./gradlew build --configuration-cache in its sandbox, which stores the task graph under .gradle/configuration-cache and fails on any problem it meets with the default problems=fail, and reads the HTML report Gradle writes under build/reports/configuration-cache. Each entry names a plugin or a build script line, and the agent takes them one at a time: a build script line that reads mutable state at configuration time is rewritten to the lazy API, a task from one of the applied plugins that is not compatible gets notCompatibleWithConfigurationCache("reason") with the reason and the plugin's issue link in the reason string, and a problem the project cannot fix is noted in the pull request rather than silenced. The startParameter line is the first candidate: the script already sets checkFormatAot.enabled = false and checkFormatAotTest.enabled = false, so the agent checks whether the exclusion still does anything and removes it if the build behaves the same without it. The documentation's problems=warn mode is not used, because an entry stored in warning mode can be incomplete and produce a wrong build on the next hit.
When the build passes with the cache, the agent writes gradle.properties with org.gradle.configuration-cache=true, so every developer and CI run uses it without the flag, and runs ./gradlew build twice more: the first stores an entry and the second must report that it reused it and skip configuration. It then runs ./gradlew test --configuration-cache once more to confirm that the Testcontainers-based tests, which start MySQL and PostgreSQL containers, still execute under the cache, after installing Docker in the sandbox with sudo apt-get install -y docker.io and starting dockerd, since the sandbox has none.
The CI change is small and specific. gradle/actions/setup-gradle@v4 only saves configuration cache entries between runs when it is given a cache-encryption-key, because the entries can hold secrets, so the agent adds that input reading a GRADLE_ENCRYPTION_KEY repository secret, documents in the pull request that the secret must be created, and leaves the workflow working without it, where each CI run configures from scratch and still passes. The cache: maven line on the JDK step of the Gradle workflow is pointed out as a leftover but not changed.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Enable the Gradle configuration cache in this build. Read settings.gradle, build.gradle, gradle/wrapper/gradle-wrapper.properties, .gitignore and every workflow under .github/workflows first. Run ./gradlew build --configuration-cache in the sandbox and read the problems report under build/reports/configuration-cache. Fix each problem at its source: rewrite build script lines that read mutable state at configuration time, mark a plugin task that cannot be made compatible with notCompatibleWithConfigurationCache and a reason, and check whether the gradle.startParameter line is still needed given the tasks the script already disables. Do not use problems=warn. Once the build passes, add gradle.properties with org.gradle.configuration-cache=true, run ./gradlew build twice and confirm the second run reuses the cache, install Docker and run the tests once more under the cache. In the Gradle workflow add cache-encryption-key from a GRADLE_ENCRYPTION_KEY secret to setup-gradle so entries are kept between CI runs, and say in the pull request that the secret must be created. Open a pull request with the report entries you fixed, the ones you marked, and the output of both runs. Do not change the Maven build or its workflow.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds gradle.properties with the one property, changes build.gradle where the report pointed, and adds the cache-encryption-key input to .github/workflows/gradle-build.yml. Its description lists every entry from the first problems report with the file or plugin it named and what was done about it, then pastes the tails of the storing run and the reusing run from the sandbox, including the line where Gradle says it reused the entry, and the test run under the cache.
Java CI with Gradle runs on the pull request with the property in place, so the reviewer sees a green build that configured under the cache on a GitHub runner. Until GRADLE_ENCRYPTION_KEY exists, that job stores no entry between runs and the description says so; the Maven workflow is unchanged and still green.
Before merging, a reviewer looks at each task marked notCompatibleWithConfigurationCache and decides whether to wait for the plugin's fix or keep the mark, creates the encryption secret so CI reuses entries, and decides whether to also add org.gradle.caching=true for the build cache, which is a separate change with its own trade-offs.
Run it on every Gradle or plugin upgrade
A plugin upgrade is where configuration cache problems come back. An automation on the Project with a github trigger on pull_request.opened and the prompt "if this pull request changes a plugin version in build.gradle or the Gradle wrapper, run ./gradlew build and report any entry in the configuration cache problems report with the plugin that caused it" checks each one. Automation runs are read-only, so the comment is all it posts, and only work by an owner, member or collaborator fires it.
A team with several Gradle builds sends this body once per repository from its own server, each a POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own build: a Kotlin DSL build gets the same fixes in build.gradle.kts, a multi-project build gets the property once at the root, and one already on problems=warn gets that line removed and the warnings it was hiding fixed.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The configuration cache is one property to enable and a list of problems to work through, and the problems are specific to the plugins a build applies and the lines its script wrote years ago. The agent runs the build in its own sandbox, reads the report Gradle produces, and fixes each entry at its source rather than switching to warning mode, which the documentation advises against because it can store a wrong entry.
Both runs, the one that stores and the one that reuses, stay with the run and are pasted into the pull request, so the review is of a build that has been shown to skip configuration on the second invocation. Several builds get the same treatment at once, each against its own plugin list.
Frequently asked questions
Why not just set problems=warn?
Because Gradle's documentation says an entry stored in warning mode may be incomplete or incorrect and can produce a wrong build on a later cache hit. The agent keeps the default problems=fail and fixes or marks each entry instead, so the cache only stores what Gradle could store fully.
What about plugins I cannot change?
A task from such a plugin is marked with notCompatibleWithConfigurationCache and a reason that names the plugin and its issue, which makes Gradle skip caching when that task runs and keeps every other task cached. The pull request lists each mark so the team can remove it when the plugin catches up.
Why does CI need an encryption key?
Because setup-gradle does not save .gradle/configuration-cache between runs unless cache-encryption-key is set, since entries can contain credentials. Without the secret the workflow still passes; it just configures from scratch each time. The description says how to create it.
Does this touch the Maven build?
No. pom.xml, mvnw and the Java CI with Maven workflow are unchanged. The configuration cache is a Gradle feature, and the property goes in gradle.properties, which Maven never reads.