# Add Checkstyle to a Maven Build

Yes. An agent adds maven-checkstyle-plugin to your pom.xml with a checked-in rule set, fixes the first violations, fails the build on new ones, and opens a PR.

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

## What the agent does

The agent reads the build before it adds a check to it. In a project laid out like spring-guides/gs-rest-service, the `complete/pom.xml` inherits `spring-boot-starter-parent` 4.0.8, sets `java.version` to 17, depends on `spring-boot-starter-webmvc` and `spring-boot-starter-webmvc-test`, and lists one plugin, `spring-boot-maven-plugin`. A Maven wrapper (`mvnw`, `.mvn/wrapper/maven-wrapper.properties`) sits beside a `build.gradle` that builds the same sources with a Java 17 toolchain. The code is three classes and one test: `RestServiceApplication`, a `Greeting` record, `GreetingController` with a `private static final String template` and a `@GetMapping("/greeting")`, and `GreetingControllerTests` using `RestTestClient`. The files use two-space indentation. `.github/workflows` runs `./mvnw --batch-mode clean package` in each variant on Temurin JDK 17 with `cache: maven`, and `test/run.sh` does the same locally. Nothing checks style.

It adds `maven-checkstyle-plugin` under `<build><plugins>` in `complete/pom.xml`, pinned to the current release on Maven Central (3.6.0 when this page was written) with the plugin's `com.puppycrawl.tools:checkstyle` dependency overridden to a current Checkstyle (14.3.0), because the version the plugin bundles lags behind. One `<execution>` binds the `check` goal to the `validate` phase with `failOnViolation` true, `consoleOutput` true and `includeTestSourceDirectory` true, so test code is held to the same rules. The rule set is a file in the repository, `complete/checkstyle.xml`, started from the bundled `google_checks.xml` because its two-space indentation matches the sources, with `violationSeverity` set to `warning` since the Google configuration reports at that level and would otherwise never fail a build. A `checkstyle-suppressions.xml` is added for generated or vendored paths, empty to begin with.

The first `./mvnw --batch-mode checkstyle:check` is the point of the exercise. On code like this the Google rules report the kind of thing a human would not bother with: `CustomImportOrder` on the blank line that separates `java.util.concurrent.atomic.AtomicLong` from the `org.springframework` imports, and `MissingJavadocType` on the public classes. The agent fixes what the report names (reorders imports, adds the short Javadoc), re-runs until the goal passes, and records in the pull request which rules fired and what it changed. Rules that the prompt says to relax are relaxed in `checkstyle.xml`, with the reason as an XML comment, rather than silenced per file.

No workflow change is needed: `validate` runs inside the existing `./mvnw --batch-mode clean package`, so the GitHub Actions job and `test/run.sh` now fail on a violation. For the report, `./mvnw checkstyle:checkstyle` writes HTML under `target/site`. The `build.gradle` is left as it is; the pull request notes that Gradle's `checkstyle` plugin can read the same `checkstyle.xml` if the team wants both builds to agree, and leaves that as a follow-up.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Checkstyle to the Maven build of this Spring Boot project. Read pom.xml, the Maven wrapper properties, every Java file under src, test/run.sh and the workflows under .github first. Add maven-checkstyle-plugin to the build plugins with its checkstyle dependency overridden to a current release, bind the check goal to the validate phase with failOnViolation, consoleOutput and includeTestSourceDirectory, and point configLocation at a checkstyle.xml committed in the project, based on google_checks.xml with violationSeverity set to warning. Add an empty checkstyle-suppressions.xml and reference it. Run ./mvnw --batch-mode checkstyle:check, fix every violation it reports in the sources, and run ./mvnw --batch-mode clean package until it passes. Do not change build.gradle. Open a pull request that lists the rules that fired and the fixes made.",
  "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 `complete/pom.xml` (the plugin block, two version properties, the `check` execution), adds `complete/checkstyle.xml` and `complete/checkstyle-suppressions.xml`, and touches the Java files the report named. Its description lists each rule that fired with the file and line, shows the final `checkstyle:check` output, and states how the check is wired into the build so the reader knows a violation now fails `clean package`.

A reviewer reads `checkstyle.xml` first, since that file decides what the team is signing up for: which Google rules stay, which were relaxed and why. Then they read the source changes, which should be small and mechanical, and confirm the plugin is pinned rather than floating. If the team prefers Sun or a house style, swapping the base file is a one-line change and the agent can be asked to re-run against it.

From then on a pull request that breaks a rule fails the existing Maven job with the rule name and line in the log, and the HTML report is one goal away for anyone who wants the full picture.

## Run it on every Java repository without a style check

A team with many Maven services sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` and carrying a `request_id` that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own `pom.xml`, so a multi-module build gets the plugin in the parent's `pluginManagement` and the rule set at the root, while a single module gets what this page describes.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "run ./mvnw checkstyle:check on this branch and post the violations as a review, citing file and line" turns the same rules into a review on every pull request until the team is comfortable letting the `validate` phase fail the build. The trigger adds the pull request after the prompt and fills in nothing else.

## Why run it on Rush?

The slow part of adding Checkstyle is not the XML, it is the first run: dozens of findings in code nobody wants to reformat by hand, and a few rules that argue with the way the team already writes Java. The agent runs the check in its own sandbox against the real build, makes the mechanical fixes, and brings back the list of rules that fired so the decision about each one is made once, in review, with the evidence in the pull request.

A reviewer reads one rule file and a small source diff. A platform team starts the same request across every Maven repository at once, each with its own JDK and wrapper, and gets one pull request per repository with the same rule set.

## Frequently asked questions

### Which rule set does it use?

Google's, as shipped in the Checkstyle jar, because this project is indented with two spaces. The file is copied into the repository as `checkstyle.xml` rather than referenced by name, so the team can edit it and so a Checkstyle upgrade cannot change the rules silently.

### Why override the Checkstyle version?

The plugin bundles an older Checkstyle than the latest release, and the Google configuration in a newer jar names modules the older engine does not know. Pinning the dependency to a current version keeps the rule file and the engine in step; the pull request records both numbers.

### Will it fail the build on day one?

Only if a violation is left, and the agent fixes every one it finds before it opens the pull request. Google's rules report at `warning` severity, so without `violationSeverity` set to `warning` the goal would pass regardless; the agent sets it so a new violation fails `validate`.

### Does it cover the Gradle build too?

Not in this pull request. The Gradle build in the same directory is left unchanged, and the description points out that Gradle's `checkstyle` plugin can read the same `checkstyle.xml` so both builds enforce one rule set.

## More Maven jobs

- [Add CodeQL Scanning to a Maven Spring Boot Project](https://getrush.ai/run/add-codeql-scanning/maven/)
- [Add Coverage Reporting to CI for a Maven Spring Boot Project](https://getrush.ai/run/add-coverage-to-ci/maven/)
- [Set Up Dependabot for a Maven Project](https://getrush.ai/run/add-dependabot/maven/)

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

- [Add a clang-format Check to CI for a CMake Project](https://getrush.ai/run/add-clang-format-check/cmake/)
- [Add clang-tidy to a CMake C++ Project and Its CI](https://getrush.ai/run/add-clang-tidy/cmake/)
- [Sort Tailwind CSS Classes with Prettier](https://getrush.ai/run/add-class-sorting/tailwind/)

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