All jobs

Migrate a Gradle Build to a Version Catalog

Yes. An agent moves every plugin and dependency version from build.gradle into gradle/libs.versions.toml, proves the resolved graph is unchanged and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the whole build before moving a version, because a catalog migration is only correct when every coordinate ends up in one place and resolves to the same thing. In a project like gothinkster/spring-boot-realworld-example-app, build.gradle is Groovy and applies five plugins with inline versions: Spring Boot 2.6.3, the Spring dependency-management plugin, java, the Netflix DGS codegen plugin and Spotless. sourceCompatibility is 11. The dependencies block mixes coordinates the Spring Boot BOM versions, such as the web, validation, hateoas, security and test starters, Flyway and Lombok, with coordinates that carry their own version: the MyBatis starter and its test starter, the DGS Spring Boot starter, three jjwt artifacts sharing one version across implementation and runtimeOnly, Joda-Time, the SQLite JDBC driver, and four REST Assured artifacts on one version. gradle/wrapper/gradle-wrapper.properties pins Gradle 7.4, there is no settings.gradle, and gradle/ holds only the wrapper. .github/workflows/gradle.yml runs ./gradlew clean test on a Zulu JDK 11 with a cache keyed on hashFiles('**/*.gradle*'), and README.md documents ./gradlew test and ./gradlew spotlessJavaApply.

Gradle 7.4 reads a gradle/libs.versions.toml from the root build automatically, so no settings file or feature flag is needed. The agent writes one with a [versions] table for each version that is shared or likely to move, springBoot, dgs, jjwt, mybatis and restAssured among them; a [libraries] table with one alias per coordinate, where BOM-managed artifacts are declared with module and no version so the Spring Boot plugin keeps choosing them; two [bundles], one for the jjwt runtime pair and one for the four REST Assured artifacts; and a [plugins] table for the four plugins that carry a version. Aliases use dashes, which Gradle turns into the dotted accessors libs.spring.boot.starter.web and libs.plugins.spring.boot.

build.gradle then shrinks to references: alias(libs.plugins.spring.boot) and its siblings in the plugins block with id 'java' left as it is, implementation libs.spring.boot.starter.web and the rest in dependencies, runtimeOnly libs.bundles.jjwt.runtime, testImplementation libs.bundles.rest.assured, and compileOnly plus annotationProcessor on libs.lombok. The Spotless, DGS generateJava and clean configuration stays untouched, as does the useJUnitPlatform() test setup. Because the CI cache key hashes only *.gradle* files, the agent adds **/libs.versions.toml to it in gradle.yml, and adds a line to README.md saying where versions now live.

Proof that nothing moved comes from Gradle itself. Before editing, the agent runs ./gradlew dependencies --configuration runtimeClasspath and the same for testRuntimeClasspath and keeps both reports; after the change it runs them again and diffs the four outputs, which must be identical. It then runs ./gradlew clean test on a JDK 11 in its sandbox, the same command the workflow uses, and ./gradlew spotlessJavaCheck, and reads any failure itself.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "codex",
  "input": "Migrate this Gradle build to a version catalog. Read build.gradle, gradle/wrapper/gradle-wrapper.properties, .github/workflows/gradle.yml, README.md and src/main/resources/application.properties first, and check whether a settings.gradle exists. Before any edit, run ./gradlew dependencies --configuration runtimeClasspath and --configuration testRuntimeClasspath and save both reports. Write gradle/libs.versions.toml with a versions table for springBoot, dgs, jjwt, mybatis, restAssured and any other shared version, a libraries table with one alias per coordinate where BOM-managed artifacts are declared with module and no version, bundles for the jjwt runtime artifacts and the REST Assured artifacts, and a plugins table for every plugin with a version. Rewrite build.gradle to use alias() in the plugins block and libs accessors in dependencies, keeping the spotless, generateJava, clean and test configuration as they are. Add **/libs.versions.toml to the cache key in gradle.yml and a note in README.md. Run the two dependency reports again and diff them against the saved ones, then ./gradlew clean test on JDK 11 and ./gradlew spotlessJavaCheck, and open a pull request that pastes the diff result and lists each alias.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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

What comes back is a pull request that adds gradle/libs.versions.toml, rewrites the plugins and dependencies blocks of build.gradle, touches one line of .github/workflows/gradle.yml and adds a note to README.md. The description lists every alias beside the coordinate it replaced, states that the runtimeClasspath and testRuntimeClasspath reports are identical before and after, and names the versions the catalog now holds in one place.

The run's record keeps the four dependency reports and their diff, the ./gradlew clean test run with every existing test, and the Spotless check, so a reviewer sees the resolved graph unchanged rather than reading the TOML and hoping.

Before merging, a reviewer decides whether Dependabot or Renovate should now watch the catalog, which both support, and whether the Spring Boot version belongs in the catalog's [versions] table or should stay the one place a major upgrade is made by hand.

Run it on every service still versioning dependencies inline

A team with several Gradle services starts one run per repository with one POST /o/{org}/sessions each, this prompt as input and the repository in resources. Each run reads its own build, so a Kotlin DSL build gets alias(libs.plugins.x) and implementation(libs.x) with parentheses, a multi-project build gets the catalog declared once at the root and used from every subproject, and a build on a Gradle older than 7.4 is reported back with the wrapper upgrade it would need first, rather than a catalog it cannot read.

Send a request_id, a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's webhook_url receives run.completed for each run the key starts, with the final answer in result.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A catalog migration is tedious and easy to get subtly wrong: a version typed once more, a BOM-managed artifact given an explicit version that overrides the BOM, a runtimeOnly artifact that lands in implementation. The agent runs Gradle's own dependency reports before and after in a sandbox of its own, with the JDK the project targets, and diffs them, so the pull request carries proof that resolution did not change instead of a request to trust it.

The full ./gradlew clean test runs on the agent's machine with its output kept in the record, and the same request can go to every Gradle service in the org at once. Each pull request arrives with its own reports and its own test run.

Frequently asked questions

Does this need a settings.gradle or a feature preview?

Not on Gradle 7.4, which the wrapper pins: a gradle/libs.versions.toml in the root build is picked up automatically as the libs catalog. The pull request adds no settings file and no flag.

What happens to artifacts the Spring Boot BOM versions?

They are declared in the catalog with module and no version, so the dependency-management plugin keeps supplying the version from the Spring Boot BOM exactly as before. Giving them a version in the catalog would override the BOM, which is the mistake the dependency report diff would catch.

Will the CI cache still work?

The workflow's cache key hashes **/*.gradle*, which does not match the TOML file, so a version bump in the catalog would reuse a stale cache. The pull request adds **/libs.versions.toml to the hashFiles call.

How do I know the build resolves the same versions?

The pull request pastes the result of diffing ./gradlew dependencies for runtimeClasspath and testRuntimeClasspath before and after the change, both kept in the run's record. An empty diff means every artifact resolved to the same version.

More Gradle jobs

More jobs like this: Hand off a long task

Keep reading