All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading