# Add Dependency Locking to a Gradle Build

Yes. An agent turns on Gradle dependency locking for every configuration and the buildscript, writes gradle.lockfile, checks the build resolves, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-dependency-locking/gradle/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how versions are chosen today. In a build laid out like spring-projects/spring-petclinic, `build.gradle` applies `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, `io.spring.nohttp` 0.0.11 and the built-in `checkstyle` plugin; the dependency block names the Spring Boot starters, `javax.cache:cache-api`, `caffeine`, `h2`, the MySQL and PostgreSQL drivers and the Testcontainers artifacts with no versions at all, because the Boot BOM supplies them through the dependency-management plugin, while the webjars and Checkstyle versions sit in `ext` properties. `settings.gradle` names the root project and nothing else, `gradle/wrapper/gradle-wrapper.properties` pins Gradle 9.5.1, `.gitignore` excludes `.gradle` and `build`, and `.github/workflows/gradle-build.yml` runs `./gradlew build` on JDK 17 through `gradle/actions/setup-gradle@v4`, after an `actions/setup-java@v4` step that still says `cache: maven`, a leftover from the Maven workflow beside it.

The BOM fixes the versions it manages, but a transitive dependency nobody declared, a `+` or range in a plugin's own dependencies, or a BOM entry that changes when a patch of Spring Boot is adopted all shift without a diff to review. Dependency locking records what every configuration resolved to and fails the build when resolution would differ. The agent adds a `dependencyLocking { lockAllConfigurations() }` block, which covers every project configuration, and `buildscript { configurations.classpath { resolutionStrategy.activateDependencyLocking() } }` for the plugins themselves, then runs `./gradlew dependencies --write-locks`. Gradle writes `gradle.lockfile` at the project root, one line per module in the form `group:artifact:version=configuration,configuration`, sorted, with an `empty=` line listing configurations that resolved nothing, and `buildscript-gradle.lockfile` beside it for the plugin classpath. Both files are meant to be committed, and the docs say to generate rather than edit them.

Then the agent decides on the mode. The default mode fails when a locked configuration resolves a different version or an extra module; `LockMode.STRICT` also fails when a locked configuration has no lock state yet, which is what catches a configuration added by a plugin after the lock files were written. That matters in this build, because the native-image and AOT plugins add configurations of their own, so the agent runs `./gradlew build`, the `cyclonedxDirectBom` task (which depends on `compileJava` and skips test configurations) and a `--dry-run` of the native tasks under `STRICT`, and adds any configuration that only resolves during those tasks to the lock files before it settles on the mode. The `cache: maven` line in the workflow is corrected to leave caching to the Gradle action, and the workflow gains nothing else: a lock mismatch fails `./gradlew build` on its own.

The pull request explains the new rhythm, because it changes how upgrades land: bumping `org.springframework.boot` in `build.gradle` now also needs `./gradlew dependencies --update-locks org.springframework.boot:*` (or `--write-locks` for everything) and the regenerated files in the same commit, and `--update-locks` takes a comma-separated list with `*` wildcards so a team can refresh one group at a time. The agent runs the full build once more from the committed lock state with a cold `GRADLE_USER_HOME` in its sandbox, so the files are proven to resolve, then opens the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add dependency locking to this Gradle build. Read build.gradle, settings.gradle, gradle/wrapper/gradle-wrapper.properties, .gitignore and .github/workflows/gradle-build.yml first. Add dependencyLocking with lockAllConfigurations for the project and activateDependencyLocking on the buildscript classpath, run ./gradlew dependencies --write-locks, and commit gradle.lockfile and buildscript-gradle.lockfile. Set lockMode to STRICT, then run ./gradlew build, the SBOM task and a dry run of any native or AOT tasks, and add lock state for every configuration they resolve so STRICT passes. Fix the setup-java cache setting in the Gradle workflow if it names maven. Run ./gradlew build once more from the committed lock files with an empty GRADLE_USER_HOME. Open a pull request that lists how many modules each lock file pins, which configurations needed extra lock state, and the --update-locks command the team runs to refresh a group.",
  "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

The pull request changes `build.gradle` and `.github/workflows/gradle-build.yml` and adds `gradle.lockfile` and `buildscript-gradle.lockfile`. Its description says how many modules each file pins and which configurations they cover, names any configuration that only resolved during the SBOM or native tasks and therefore needed a second `--write-locks` pass, states the lock mode it chose and why, and quotes the final `./gradlew build` from a cold cache in the sandbox.

A reviewer checks the mode against the team's tolerance for a failing build when a plugin adds a configuration, reads the `--update-locks` instruction and decides whether to put it in the contributing guide, and confirms the lock files are in the same commit as the configuration so the branch never has one without the other.

From then on a dependency change is visible as a diff in `gradle.lockfile`: a Boot patch that moves a transitive version shows the line that moved, and a module that appears without a declaration shows up as a new line to question.

## Run it on every Monday morning

An automation on the Project with a `schedule` trigger (`cron` `0 9 * * 1` in your `timezone`) and the prompt "run ./gradlew dependencies --update-locks for every module, run ./gradlew build, and open a pull request whose description groups the lock file diff by group and names any build or test failure next to the line that caused it; leave out any update that breaks the build and say why" turns the lock files into the place upgrades are reviewed. Each run opens one pull request on its own branch, and a week with no resolution change opens none.

A team with several Gradle builds sends the locking request once per repository from its own server, each `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 multi-project build gets a `gradle.lockfile` per subproject, and one with a `settings.gradle` plugin block gets its settings classpath locked as well.

## Why run it on Rush?

The lock files are only right when they were written by a build that resolved every configuration, and a build with native-image, AOT, SBOM and Testcontainers configurations resolves different sets in different tasks. The agent runs those tasks in its own sandbox under the strict mode until the lock state is complete, then proves the result from an empty Gradle cache, and keeps every run with the pull request.

A reviewer sees how many modules are pinned, which configurations needed care and the exact refresh command, rather than two large generated files and a one-line build change. A team with several builds starts the same request across all of them at once.

## Frequently asked questions

### I already use the Spring Boot BOM. Why lock as well?

The BOM fixes the versions it manages; it does not record what a build resolved. A transitive module outside the BOM, a plugin dependency, or a BOM entry that moves with a Boot patch all change without a reviewable diff. The lock file is that diff, and the BOM keeps doing its job underneath it.

### Which lock mode should I use?

`STRICT` fails when a locked configuration has no lock state, which catches a configuration a plugin added after the files were written; the default only fails on a mismatch. `LENIENT` pins dynamic versions and tolerates added or removed modules, which suits a build mid-migration. The agent picks `STRICT` when every configuration in the build can be made to resolve, and says so.

### How do upgrades work now?

Change the version in `build.gradle` and run `./gradlew dependencies --update-locks group:module` for what should move, or `--write-locks` for everything, and commit the regenerated lock files with the change. `--update-locks` takes a comma-separated list and allows `*` in a group or module name, so one group can be refreshed on its own.

### Does this replace a version catalog?

No. A catalog says what you declared; a lock file says what resolved, transitives included. They work together, and a build that adds a catalog later keeps its lock files unchanged.

## More Gradle jobs

- [Add Dependency Verification to a Gradle Build](https://getrush.ai/run/add-dependency-verification/gradle/)
- [Add a Dockerfile to a Gradle Spring Boot App](https://getrush.ai/run/add-dockerfile/gradle/)
- [Add Error Prone to a Gradle Build](https://getrush.ai/run/add-errorprone/gradle/)

## More jobs like this: Upgrade dependencies weekly

- [Add mix audit Dependency Scanning to an Elixir Project](https://getrush.ai/run/add-mix-audit/elixir/)
- [Add NuGet Vulnerability Auditing to a .NET Solution's CI](https://getrush.ai/run/add-nuget-audit-to-ci/dotnet/)
- [Add pip-audit to a Python Project's CI](https://getrush.ai/run/add-pip-audit-to-ci/python/)

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