What the agent does
The agent reads the build before adding a plugin to it. In an app laid out like gothinkster/spring-boot-realworld-example-app, build.gradle applies org.springframework.boot 2.6.3, io.spring.dependency-management 1.0.11.RELEASE, java, the DGS codegen plugin 5.0.6 and Spotless 6.2.1 with googleJavaFormat(), sets sourceCompatibility and targetCompatibility to 11, and pulls Lombok as compileOnly and annotationProcessor. gradle/wrapper/gradle-wrapper.properties pins Gradle 7.4. The generateJava task writes DGS types into build/generated under the io.spring.graphql package, and tasks.named('test') uses JUnit Platform. .github/workflows/gradle.yml sets up JDK 11 and runs ./gradlew clean test, not check. The main source set has 93 Java files across io.spring.api, core, application, graphql and infrastructure, and Lombok is everywhere: 33 files import AllArgsConstructor, 18 NoArgsConstructor, 15 Getter, 8 Data, 5 EqualsAndHashCode. Two classes already carry a @SuppressWarnings, in InvalidRequestException and JwtTokenFilter.
The plugin is com.github.spotbugs, whose current version on the Gradle plugin portal is 6.5.13; its migration notes say the 6 line needs Gradle 7.1 or later, so the 7.4 wrapper stays. The agent adds it to the plugins block, configures the spotbugs extension with ignoreFailures = false, showStackTraces = true, effort and reportLevel from the plugin's enums, and excludeFilter = file('config/spotbugs/exclude.xml'), and sets the spotbugsMain task to write an HTML and an XML report. spotbugsTest is disabled: the tests use REST Assured and Mockito patterns that trip null and unused-value detectors by design, and the point of the first pass is the production code. The plugin's toolVersion is left at the plugin's default unless the first run shows a reason to pin it.
The first ./gradlew spotbugsMain run is the real work, and the agent reads build/reports/spotbugs/main.html finding by finding. Three groups come out of a codebase like this. Generated DGS classes in io.spring.graphql.types are excluded by package in the filter, since nobody edits them. Lombok-generated accessors on @Data and @Getter classes that return a mutable field (a List of tags, a DateTime) produce EI_EXPOSE_REP and EI_EXPOSE_REP2; the agent scopes those two patterns to the packages where the entities live rather than disabling them globally, with a comment in the filter saying why. Everything else is a candidate fix: an unclosed resource, a comparison of boxed types, a field read before assignment, a String built in a loop. Each fix is its own commit so a reviewer can accept them one at a time, and ./gradlew spotlessJavaApply runs afterwards so the formatter does not fight the change.
CI changes last. Since the plugin attaches its tasks to check and the workflow runs test, the agent changes the step to ./gradlew clean check, which runs SpotBugs and the tests, and uploads build/reports/spotbugs as a workflow artifact so a failing run shows its report. It confirms the whole thing on JDK 11 as the workflow does, runs ./gradlew clean check twice to show the second run is clean, and adds a README paragraph next to the existing Spotless note: how to run SpotBugs locally, where the report lands and how to add an exclusion.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add SpotBugs static analysis to this Gradle and Spring Boot project. Read build.gradle, settings.gradle, gradle/wrapper/gradle-wrapper.properties, .github/workflows/gradle.yml, README.md, src/main/resources/application.properties and the package layout under src/main/java first, and note where Lombok and the DGS code generator are used. Add the com.github.spotbugs plugin at its current version, configure the spotbugs extension with ignoreFailures false, showStackTraces true, an effort and report level, and an exclude filter at config/spotbugs/exclude.xml; make spotbugsMain write HTML and XML reports and disable spotbugsTest. Run ./gradlew spotbugsMain, read the report, fix every real finding in its own commit, exclude the generated DGS package, scope EI_EXPOSE_REP and EI_EXPOSE_REP2 to the entity packages where Lombok accessors return mutable fields, and comment each exclusion with its reason. Run spotlessJavaApply after the fixes. Change the CI step to ./gradlew clean check and upload the SpotBugs report directory as an artifact. Run clean check twice on JDK 11, add a README section, and open a pull request that quotes the final report summary and the test output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 (the plugin, the extension and the two task settings), .github/workflows/gradle.yml (the check step and the artifact upload) and README.md, adds config/spotbugs/exclude.xml, and carries one commit per fixed finding in src/main/java. Its description lists each fix with the SpotBugs pattern it answered and the file, lists each exclusion with its reason, and quotes the summary line of the final report and the ./gradlew clean check output.
A reviewer goes through the exclusions first, since those are the judgement calls: whether scoping EI_EXPOSE_REP to the entity packages hides anything they care about, and whether the generated package exclusion is wide enough once more DGS types are generated. Then the fixes, which are small and self-contained by design, and finally the reportLevel, which decides how noisy the next pull request's check will be.
The build's other plugins, the test task and the Spotless configuration are untouched. A developer who runs ./gradlew check gets the same report CI does, in build/reports/spotbugs/main.html.
Run it on every pull request
Once the baseline is clean, every pull request should be read against it. An automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize runs read-only with a prompt that runs ./gradlew spotbugsMain on the branch, compares the XML report with the one from the base branch, and comments on the pull request with only the findings the change introduced, each with its pattern, file and line. The event the trigger adds after the prompt names the pull request; the prompt holds no placeholder.
Work by a repository owner, member or collaborator fires the trigger; pull requests from forks and bot senders never do, so a Dependabot bump is not analysed this way. For the base-branch report the automation reads what the last check run uploaded as an artifact, or runs the base once itself when there is none, and its max_runs_per_hour caps how many pushes to one branch start a run.
The use case this job follows, with its automation and trigger: Review every pull request.
Why run it on Rush?
The first SpotBugs run on an existing codebase is a triage job, not a configuration job: hundreds of findings have to be read, sorted into real bugs, intended patterns and generated code, and the exclusions written so the next run is quiet without being blind. The agent does that reading in its own sandbox with the report in front of it and keeps the report, the fixes and the reasons in the run's record, so the reviewer sees why each line in the filter exists.
A company with several Gradle services wants the same analyser at the same level in each, with exclusions that follow the same rules. One run per repository reads that build and that code, writes its own filter, and opens one pull request each, and the README paragraph and CI step come out the same everywhere.
Frequently asked questions
Will it fail the build on the first run?
After the pull request, no: the agent fixes or excludes every finding before it sets ignoreFailures = false, and runs clean check twice to prove the second run is clean. Before the triage, with the plugin alone, it would, which is why the triage is part of the job.
Why exclude EI_EXPOSE_REP for the entities?
Lombok writes the getters and constructors for @Data and @Getter classes, and SpotBugs flags any accessor that hands out a mutable field. Rewriting those accessors by hand defeats Lombok. The exclusion is scoped to the entity packages and the two patterns, so an exposed collection elsewhere still shows up.
What about the generated GraphQL classes?
The DGS plugin writes them into build/generated on every build, so a fix there is lost at once. The filter excludes their package, and the pull request says which package that is so it can be widened when the schema grows.
Does this need a newer Gradle?
The plugin's migration notes say its current major line needs Gradle 7.1 or later and the wrapper is 7.4, so no. If a future plugin release raises that, the wrapper upgrade is a separate change, and the agent notes the version it used.
Why change CI to check instead of test?
The plugin attaches spotbugsMain to the check lifecycle task, and test does not depend on it. Running check keeps the tests and adds the analysis in one step; the uploaded report artifact is what a developer opens when the step fails.
More Gradle jobs
The same job on other stacks
- Add SpotBugs to a Maven Build (Maven)