What the agent does
The agent reads the workflows that exist before it writes one, so the scanner runs on the same events and toolchain as the build. In a project like spring-projects/spring-petclinic there are three: maven-build.yml runs ./mvnw -B verify on push and pull request to main, on ubuntu-latest, with actions/setup-java@v4 on a one-entry matrix of Java 17 and the adopt distribution; gradle-build.yml does the same with ./gradlew build; and deploy-and-test-cluster.yml runs only when k8s/ changes. There is no CodeQL workflow, no security-events permission anywhere, no dependabot.yml under .github/, only dco.yml. pom.xml inherits spring-boot-starter-parent 4.1.0, sets java.version to 17, and binds spring-javaformat:validate, a nohttp Checkstyle check and the enforcer to the validate phase, JaCoCo to the test phases and CycloneDX to the package phase; .mvn/wrapper/maven-wrapper.properties pins Maven 3.9.16. The sources are one module under src/main/java/org/springframework/samples/petclinic/ with model, owner, system and vet packages and Thymeleaf templates under src/main/resources/templates/; there is no Kotlin and no code generation step.
From that the agent writes .github/workflows/codeql.yml. It triggers on push to main, on pull_request to main and on a weekly schedule, with a permissions block of security-events: write, contents: read and actions: read. One job on ubuntu-latest checks out with actions/checkout@v7, sets up Java 17 with actions/setup-java@v6 and the temurin distribution, runs github/codeql-action/init@v4 with languages: java-kotlin and build-mode: none, and github/codeql-action/analyze@v4 with category: "/language:java-kotlin". none is the mode CodeQL's own README lists as available for Java: the database is built from the sources without running Maven, which keeps the scan off the validate-phase format and Checkstyle checks and the Testcontainers tests, and is the right choice for a project with no generated code; the pull request explains that manual with ./mvnw -B -DskipTests package is the fallback if a later change adds code generation. The JDK step is kept so that fallback is one line away and so the toolchain matches java.version.
Pinning follows the repository: the existing workflows pin by major tag, actions/checkout@v4 and actions/setup-java@v4, and nothing updates them, so the new file pins by major tag too and the description says that a dependabot.yml with a github-actions entry is the follow-up that would keep all four workflows current. The agent does not touch maven-build.yml, including its adopt distribution, which setup-java still accepts as an alias; CodeQL is a separate check that should pass or fail on its own.
Validation happens in the sandbox. The agent installs actionlint and runs it on the new file, then runs ./mvnw -B -DskipTests package on Java 17 to show the sources compile with the toolchain the manual fallback would use, and keeps both outputs for the pull request. The analysis and the upload happen on GitHub's runners, so the first result appears as the CodeQL check on the pull request itself; the description tells the reviewer to look there and under the Security tab after merge, and to make sure code scanning's default setup is not turned on for the repository, since GitHub refuses an advanced-setup upload while it is.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add CodeQL scanning to this Maven Spring Boot project. Read pom.xml, .mvn/wrapper/maven-wrapper.properties, .github/workflows/maven-build.yml, .github/workflows/gradle-build.yml, .github/workflows/deploy-and-test-cluster.yml, .github/dco.yml and the package layout under src/main/java first. Write .github/workflows/codeql.yml that runs on push to main, on pull_request to main and on a weekly schedule, with permissions limited to security-events write, contents read and actions read, one job on ubuntu-latest using actions/checkout@v7, actions/setup-java@v6 with Java 17 and temurin, github/codeql-action/init@v4 with languages java-kotlin and build-mode none, and github/codeql-action/analyze@v4 with category /language:java-kotlin. Pin by major tag like the existing workflows and say in the pull request that a Dependabot github-actions entry is the follow-up. Do not change the existing workflows. Install actionlint and run it on the new file, run ./mvnw -B -DskipTests package on Java 17, and open a pull request that pastes both outputs, explains why build-mode none fits this project and when to switch to manual, and tells the reviewer where the first result appears and to check that default setup is not enabled.",
"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
What comes back is a pull request that adds one file, .github/workflows/codeql.yml. The description lists the triggers, the three permissions, the four actions with their major tags, the reason build-mode: none was chosen for a Java project with no code generation and what would change it, and the actionlint and ./mvnw -B -DskipTests package output from the sandbox.
The run's record holds the actionlint install and run and the Maven compile with the wrapper's pinned Maven 3.9.16 and the dependency download that implies. Nothing else in the repository changes, and maven-build.yml and gradle-build.yml keep running as they were.
Before merging, a reviewer checks the repository's code security settings: if default setup is on, it is turned off before this workflow runs, or the upload is refused. After merge, every pull request and the weekly schedule produce results under the Security tab, and the follow-up Dependabot entry keeps the action tags current for all four workflows.
Run it on every new Java repository
An organisation with many Maven services starts one run per repository from its own server: one POST /o/{org}/sessions each, 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 rather than a second pull request. Each run reads that repository's own workflows, so one that pins actions by SHA gets SHA pins, one with Kotlin sources gets a manual build mode, and a multi-module build gets the same none mode with no build step.
Afterwards, an automation on the Project with a github trigger on workflow_run.failure and the prompt "if the failed workflow is CodeQL, read its log, say whether the database build or the upload failed, and propose the fix as a comment" turns a red scan into a diagnosis. The trigger adds the event after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A CodeQL workflow for Java is twenty lines, and the choices that matter are easy to get wrong without reading the project: a build mode that drags the format and Checkstyle checks and the Docker-backed tests into every scan, a JDK older than java.version, a missing security-events permission, pins that nothing keeps current, and a default-setup conflict that refuses the upload after merge. The agent reads the build workflow and the pom.xml first, writes the file to match them, and lints it before anyone waits on a runner.
In its own sandbox the agent runs actionlint and the Maven compile, and the run keeps that output for the pull request. For an organisation with many Java repositories, each gets its own run and its own pull request shaped by its own build, rather than a template pasted into each.
Frequently asked questions
Why build-mode none and not autobuild?
CodeQL's README lists none as available for Java, and this project has no code generation, so the sources alone give a complete database. autobuild would run the Maven build on every scan, including the validate-phase format and Checkstyle checks and the test phase, which is slower and fails for reasons unrelated to security. If a later change adds generated sources, the pull request names the manual mode and the exact build command to switch to.
Does it scan the Gradle build too?
It scans the sources, which both builds compile, so one analysis covers the project. With build-mode: none neither build runs during the scan; gradle-build.yml and maven-build.yml keep running as they do today.
Why temurin when maven-build.yml uses adopt?
adopt is the older name setup-java still accepts as an alias, and temurin is where those builds come from today. The new workflow uses the current name and leaves maven-build.yml as it is, since changing it is not part of adding a scanner; the description notes it as a one-word follow-up.
Can the agent run CodeQL before opening the PR?
Not usefully. The analysis and the upload to code scanning run on GitHub's side, so the agent validates the workflow with actionlint and proves the sources compile on Java 17. The first scan appears as the CodeQL check on the pull request itself, because the workflow triggers on pull_request.
What keeps the action versions current?
Nothing, today: the existing workflows pin checkout@v4 and setup-java@v4 by major tag with no Dependabot config in the repository. The new file matches that, and the pull request names a dependabot.yml with a github-actions entry as the follow-up that would move all four workflows together.
More Maven jobs
The same job on other stacks
- Add CodeQL Scanning to a TypeScript Library (TypeScript library)
- Add CodeQL Scanning to a CMake C++ Project (CMake)
- Add CodeQL Scanning to a Cobra CLI (Cobra)