# Add PMD Static Analysis to a Maven Build

Yes. An agent adds maven-pmd-plugin to your build with a ruleset tuned to the code, settles the first findings, fails verify on new ones, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pmd/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 plugin. In a project like spring-projects/spring-petclinic, `pom.xml` inherits `spring-boot-starter-parent` 4.1.0, sets `java.version` to 17 (the parent turns that into `maven.compiler.release`), and already runs three checks before compilation: `maven-enforcer-plugin` for the Java version, `spring-javaformat-maven-plugin` on `validate`, and `maven-checkstyle-plugin` 3.6.0 with checkstyle 12.3.1 and `nohttp-checkstyle` over `src/checkstyle/nohttp-checkstyle.xml`, which only forbids plain `http://` URLs. JaCoCo 0.8.15, `git-commit-id`, CycloneDX and the native plugin complete the list; there is no PMD, SpotBugs or Error Prone. `.github/workflows/maven-build.yml` runs `./mvnw -B verify` on JDK 17, `gradle-build.yml` runs the Gradle twin of the build, and the sources are 30 files across `model`, `owner`, `system` and `vet`, with 20 test classes, three of which need Docker for MySQL and Postgres.

The plugin goes into `<build><plugins>` as `maven-pmd-plugin` 3.28.0, which bundles PMD 7.17.0, with one execution that binds the `check` and `cpd-check` goals to `verify`, `failOnViolation` true, `printFailingErrors` true so the violations appear in the Maven log, `linkXRef` false so the build does not need the JXR plugin, `targetJdk` set from `java.version`, and `excludeRoots` for the generated sources the native plugin can leave under `target/`. Rules come from a project file, `src/pmd/ruleset.xml`, that includes `category/java/bestpractices.xml` and `category/java/errorprone.xml` and a chosen subset of `design.xml`, rather than every category: codestyle rules such as `AtLeastOneConstructor` or `LongVariable` would fight the project's Spring conventions and the formatter already enforces layout. Tests are analysed too, with the JUnit-specific rules that do not fit `@WebMvcTest` classes excluded by name.

The first `./mvnw -B verify` in the sandbox is the baseline, and it decides the rest of the pull request. Each violation is either fixed where the fix is mechanical and local, suppressed with `@SuppressWarnings("PMD.RuleName")` and a reason where the code is right, or dropped from the ruleset where the rule is wrong for this codebase, and the description lists every one of those decisions with the file and line. The run ends with `verify` green and the rule count that will now fail a pull request. Because CI builds the Gradle side too, `build.gradle` gets the `pmd` plugin pointed at the same `src/pmd/ruleset.xml` and the same PMD version, so both builds report the same findings.

The agent installs a JDK 17 in its sandbox, uses the Maven wrapper (`.mvn/wrapper/maven-wrapper.properties` pins 3.9.16) and the Gradle wrapper, runs `./mvnw -B verify` and `./gradlew check`, and reads `target/pmd.xml` and `target/cpd.xml` for the counts it quotes. The three database integration tests that need Docker run after it installs Docker in the sandbox, since the sandbox has none by default; if that step fails, the pull request says which tests ran and which did not.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add PMD to this Maven build. Read pom.xml, build.gradle, .mvn/wrapper/maven-wrapper.properties, .github/workflows/maven-build.yml, .github/workflows/gradle-build.yml, src/checkstyle/nohttp-checkstyle.xml and the test classes under src/test/java first. Add maven-pmd-plugin 3.28.0 with an execution binding check and cpd-check to verify, failOnViolation and printFailingErrors true, linkXRef false, targetJdk from java.version, and a ruleset file at src/pmd/ruleset.xml that includes category/java/bestpractices.xml, category/java/errorprone.xml and a chosen subset of design.xml, excluding rules that conflict with Spring conventions and the test classes' style. Add the pmd plugin to build.gradle using the same ruleset and PMD version. Install JDK 17, run ./mvnw -B verify and ./gradlew check, and for every violation either fix it, suppress it with @SuppressWarnings and a reason, or remove the rule, recording each decision. Install Docker in the sandbox so the MySQL and Postgres integration tests can run, and say which tests ran. Open a pull request with the baseline counts, the decisions, and the command that reproduces the report.",
  "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 `pom.xml` and `build.gradle`, adds `src/pmd/ruleset.xml`, and touches the Java files whose findings were fixed or suppressed. Its description has three parts: the rule categories included and the named exclusions with one line of reasoning each, the baseline table from `target/pmd.xml` and `target/cpd.xml` with how each finding was handled, and the Maven and Gradle output from the sandbox showing `verify` and `check` passing.

It is explicit about what changed in behaviour: `./mvnw -B verify` in `maven-build.yml` now fails on any PMD or CPD finding, which means a contributor's pull request fails on a new unused field or duplicated block before a human reads it, and the report is at `target/site/pmd.html` once `./mvnw pmd:pmd` has run. It also notes that `nohttp-checkstyle` and `spring-javaformat` stay as they were, because PMD checks different things.

Before merging, a reviewer reads the suppressions, decides whether `minimumPriority` should start at 3 and tighten later, and chooses whether CPD's minimum token count suits a codebase with repetitive Spring controllers.

## Run it on every Maven repository without static analysis

A platform team with many Maven services sends this body 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 `pom.xml`: a service that already runs SpotBugs gets PMD beside it with overlapping rules dropped, a multi-module build gets the plugin in the parent's `pluginManagement`, and a service on an older Boot parent gets `targetJdk` from whatever that parent sets.

After the first merge, an automation on the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt 'run ./mvnw -B pmd:check on this pull request and, for each new finding, post a review comment with the rule, the line and the smallest fix' starts one run per push. The trigger adds the pull request after the prompt and fills in nothing else, so the review names the rule that fired rather than restating the build log.

## Why run it on Rush?

Adding PMD to an existing build is a negotiation with the code: the first run finds things, and a plugin that fails `verify` from day one without that negotiation gets disabled by the next person who needs to ship. The agent runs the baseline, makes a decision for every finding with the file and line in front of it, and keeps the ruleset to the categories that catch bugs rather than taste, so what lands is a check the team will keep.

The Maven and Gradle output, the report files and the diff stay with the run, so a reviewer can see the finding count before and after and the exact command that produced it. A team with many services runs the same request across all of them at once, each build in its own sandbox.

## Frequently asked questions

### Does this replace Checkstyle or Error Prone?

No. Checkstyle in this project only enforces `nohttp`, the formatter enforces layout, and PMD looks for bug patterns, unused code and dead stores in the source. Error Prone works inside the compiler and catches a different set. They coexist, and the pull request leaves the existing plugins untouched.

### Which PMD version runs?

maven-pmd-plugin 3.28.0 bundles PMD 7.17.0. To move PMD forward without waiting for the plugin, the `net.sourceforge.pmd` artifacts can be declared as plugin dependencies at a newer version, and the pull request shows that block commented out so a reviewer knows where it goes.

### Will the build fail on day one?

Not after the pull request, because the agent fixes, suppresses or excludes every baseline finding and runs `verify` green before opening it. From then on a new finding fails `verify`, which is the point. If the team prefers a warning phase, `failOnViolation` can be false for a sprint while `printFailingErrors` still shows the list.

### Does the Gradle build get the same checks?

Yes. `build.gradle` gets the `pmd` plugin with the same ruleset file and PMD version, so `./gradlew check` fails on the same findings `./mvnw verify` does. Keeping one ruleset file for both avoids the two builds drifting apart.

## More Maven jobs

- [Add a Release Workflow for a Maven Library](https://getrush.ai/run/add-release-workflow/maven/)
- [Make a Maven Build Reproducible](https://getrush.ai/run/add-reproducible-builds/maven/)
- [Add an SBOM to CI for a Maven Project](https://getrush.ai/run/add-sbom-to-ci/maven/)

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

- [Add Pod Disruption Budgets to Argo CD Applications](https://getrush.ai/run/add-pod-disruption-budgets/argo-cd/)
- [Add Pod Disruption Budgets to a GKE App](https://getrush.ai/run/add-pod-disruption-budgets/gke/)
- [Add a Pod Disruption Budget to a Helm Chart](https://getrush.ai/run/add-pod-disruption-budgets/helm/)

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