# Add Spotless Formatting to a Maven Build

Yes. An agent adds the Spotless Maven plugin with google-java-format to your pom.xml, formats the sources once, makes CI fail on unformatted code, and opens a PR.

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

## What the agent does

The agent starts with what the build is, because a formatter has to attach to it. In a project like spring-guides/gs-rest-service, `complete/pom.xml` and `initial/pom.xml` each inherit from `spring-boot-starter-parent` 4.0.8, set `java.version` to 17, depend on `spring-boot-starter-webmvc` and its test starter, and declare only the `spring-boot-maven-plugin`. Both folders carry a Maven wrapper whose `.mvn/wrapper/maven-wrapper.properties` pins Maven 3.9.16, and the same two folders also have a `build.gradle`; `complete-kotlin` and `initial-kotlin` are Gradle-only. `.github/workflows/continuous-integration-build.yml` sets up JDK 17 and runs `./mvnw --batch-mode clean package` in `initial` and `complete` before the Gradle builds, and `test/run.sh` does the same by hand.

Then it reads the sources to pick a style that fits them rather than one that rewrites everything. `complete/src/main/java/com/example/restservice` holds a `Greeting` record, a `GreetingController` with one `@GetMapping` and a `RestServiceApplication`, and the test `GreetingControllerTests` uses `RestTestClient` in chained calls; all of it is indented with two spaces. That matches google-java-format's output, so the agent picks the `googleJavaFormat` step, which also orders imports and removes unused ones, and expects a small first diff, mostly in the test's chained calls, which it keeps in its own commit so the reviewer can see the formatter's taste separately from the plugin.

The change to each `pom.xml` is one plugin under `build/plugins`: `spotless-maven-plugin` with a `<java>` block that sets `googleJavaFormat` and the default includes, `src/main/java` and `src/test/java`, and an `<execution>` that binds the `check` goal to the `validate` phase. That phase matters: the workflow runs `clean package`, which never reaches `verify`, so a check left on the goal's default phase, `verify`, which the plugin's README names, would pass CI without running. Bound to `validate`, an unformatted file fails `./mvnw --batch-mode clean package` before compilation, in both folders, with no workflow change. The agent pins the plugin version it resolves at run time and notes the `ratchetFrom` option in the pull request for a repository with a large unformatted history.

It then runs the formatter once with `./mvnw spotless:apply` in `initial` and `complete`, commits the result, and runs `./mvnw --batch-mode clean package` in both to prove the check passes and the two tests in `GreetingControllerTests` still do. To prove the check fails when it should, it re-indents one line, runs `./mvnw spotless:check`, keeps the failure output for the run's record, and restores the line. The Gradle builds and the Kotlin folders are left as they are; the pull request says that the Spotless Gradle plugin would cover them and that this change is scoped to Maven.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Spotless formatting to the Maven builds in this repository. Read .github/workflows/continuous-integration-build.yml, test/run.sh, .github/dependabot.yml, complete/pom.xml, initial/pom.xml, complete/.mvn/wrapper/maven-wrapper.properties and every Java file under complete/src and initial/src first. Add spotless-maven-plugin to both pom.xml files with a java block using googleJavaFormat on the default includes, and bind the check goal to the validate phase so that the workflow's existing ./mvnw --batch-mode clean package fails on an unformatted file without any workflow change. Pin the plugin version you resolve. Run ./mvnw spotless:apply in both folders and commit the formatting changes as their own commit, separate from the plugin commit. Run ./mvnw --batch-mode clean package in both folders, then break the formatting of one line, run ./mvnw spotless:check to show it fails, and restore it. Leave the Gradle builds and the Kotlin folders unchanged and say so. Open a pull request that explains the phase choice and mentions ratchetFrom for repositories with a large unformatted history.",
  "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 with two commits: one that adds the plugin to `complete/pom.xml` and `initial/pom.xml`, and one that holds every formatting change `spotless:apply` made. The description explains why `check` is bound to `validate` and not `verify`, with the line from the workflow that shows `clean package` stops short of `verify`, and lists the Gradle and Kotlin folders as out of scope with the plugin that would cover them.

The run's record keeps the `spotless:apply` diff summary, the passing `clean package` in both folders with the `GreetingControllerTests` output, and the deliberate `spotless:check` failure with its message, so a reviewer can see the check both pass and fail without running Maven.

Before merging, a reviewer decides whether google-java-format's import ordering is what the team wants, whether to add `ratchetFrom` so only files changed since a base commit are checked, and whether the Gradle builds should get the matching plugin in the same pull request or a later one. The agent takes no position on the last and shows the Gradle snippet in the description.

## Run it on every pull request

Once the plugin is in, CI enforces it on every push. For a review that explains failures, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "run ./mvnw spotless:check in each Maven folder this pull request touches; if it fails, comment with the files and the diff spotless:apply would make" reads each new pull request. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

The same automation can take a `branch_patterns` filter so it runs only for pull requests against `main`, and its `max_runs_per_hour` cap bounds a busy afternoon of pushes.

## Why run it on Rush?

A formatter added without running it ships one of two surprises: a first diff nobody expected, or a check bound to a phase CI never reaches. The agent runs the formatter and the build in its own sandbox, commits the formatting apart from the plugin, and breaks a line on purpose to see the check fail, so the pull request shows both outcomes.

Every command stays with the run, from `spotless:apply` to the deliberate failure, and the pull request can cite them. Doing the same across every Maven repository a team owns at once costs no more attention than one, because each run has its own machine and its own record.

## Frequently asked questions

### Why bind check to validate instead of verify?

Because `.github/workflows/continuous-integration-build.yml` runs `./mvnw --batch-mode clean package`, and `package` comes before `verify` in Maven's lifecycle. A check bound to `verify` would never run in CI. `validate` is the first phase, so an unformatted file fails before anything compiles, and the workflow needs no new step.

### Will the first commit reformat a lot?

The sources already use two-space indentation, which is google-java-format's style, so the diff is small: import order and the wrapping of the chained `RestTestClient` calls in the test. The agent keeps it in its own commit so the reviewer can judge the formatter's output on its own.

### What about the Gradle builds and the Kotlin folders?

Unchanged. `complete` and `initial` also have a `build.gradle`, and the Kotlin folders are Gradle-only; Spotless has a Gradle plugin and a `ktlint` step for them. The question was about Maven, so the pull request shows the Gradle snippet and leaves the decision to the reviewer.

### Can the check be limited to changed files?

Yes, with `ratchetFrom`, which tells Spotless to check only files that differ from a base commit or branch. It suits a repository with years of unformatted history; this one is small enough to format in one commit, so the agent mentions the option without using it.

## More Maven jobs

- [Fix "Source option 5 is no longer supported. Use 7 or later." in Maven](https://getrush.ai/run/fix-source-option-5-no-longer-supported/maven/)
- [Migrate a Jenkins Pipeline to GitHub Actions for a Maven Project](https://getrush.ai/run/migrate-jenkins-to-github-actions/maven/)
- [Add ArchUnit Architecture Tests to a Maven Spring Boot Project](https://getrush.ai/run/add-architecture-tests/maven/)

## More jobs like this: Review every pull request

- [Address Review Comments on a Laravel Pull Request](https://getrush.ai/run/answer-review-comments/laravel/)
- [Address Review Comments on a Rails Pull Request](https://getrush.ai/run/answer-review-comments/rails/)
- [Review Accessibility in Angular Pull Requests](https://getrush.ai/run/review-accessibility/angular/)

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