# 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 Rush](https://cloud.getrush.ai/run/migrate-to-version-catalog/gradle/). Opens 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`

```json
{
  "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`.

## 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

- [Update the GitHub Actions in a Gradle Build's Workflow](https://getrush.ai/run/update-github-actions/gradle/)
- [Upgrade Gradle Dependencies Weekly for a Spring Boot App](https://getrush.ai/run/upgrade-gradle-dependencies/gradle/)
- [Add CodeQL Scanning to a Gradle Project](https://getrush.ai/run/add-codeql-scanning/gradle/)

## More jobs like this: Hand off a long task

- [Move a Koa Project from Travis CI to GitHub Actions](https://getrush.ai/run/migrate-travis-to-github-actions/koa/)
- [Move a Mongoose API from Travis CI to GitHub Actions](https://getrush.ai/run/migrate-travis-to-github-actions/mongoose/)
- [Migrate a Python Project from Travis CI to GitHub Actions](https://getrush.ai/run/migrate-travis-to-github-actions/travis-ci/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
