All jobs

Add the Maven Wrapper to a Maven Project

Yes. An agent reads your POM and CI workflow, generates mvnw with the Maven version your build needs, switches CI to the wrapper, builds through it 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 how the project is built before it generates anything. In a library like jhy/jsoup the whole build is one pom.xml: a multi-release jar assembled by maven-compiler-plugin in several executions (a Java 8 base, a Java 11 overlay on newer JDKs, API checks through animal-sniffer-maven-plugin), maven-surefire-plugin and maven-failsafe-plugin with JUnit running in parallel, japicmp-maven-plugin against the previous release, and central-publishing-maven-plugin for the release profile. The POM declares no <prerequisites> and no enforcer rule for a Maven version, so whatever mvn is on the path builds it, which is the gap the wrapper closes. .github/workflows/build.yml runs mvn -X compile -B --file pom.xml and mvn -X verify -B --file pom.xml on a matrix of three operating systems and JDK 8, 17 and 25, using whatever Maven ubuntu-latest, windows-latest and macOS-latest ship that week; cifuzz.yml and codeql.yml build the same way. .gitignore lists IDE files and target/ but nothing wrapper-related, and .gitattributes sets text=auto eol=lf, which matters for a shell script that must run on Windows checkouts.

It generates the wrapper with Maven's own plugin, mvn -N wrapper:wrapper -Dmaven=<version>, choosing the newest Maven release that the project's plugins support. That writes mvnw, mvnw.cmd and .mvn/wrapper/maven-wrapper.properties; with the plugin's current defaults the properties file records wrapperVersion, distributionType=only-script and a distributionUrl on repo.maven.apache.org for the chosen apache-maven-<version>-bin.zip. The only-script type means no jar is committed: mvnw is a shell script that downloads the distribution into ~/.m2/wrapper/dists on first use and verifies it when a distributionSha256Sum is set, so the agent reads the published checksum for that zip and adds it to the properties, which is what makes the wrapper safe to run in CI. It marks mvnw executable in git with git update-index --chmod=+x, since a mode bit lost in a checkout is the usual reason a wrapper fails on the first machine.

Then it moves every build to the wrapper. The two mvn steps in build.yml become ./mvnw, with the --file pom.xml and -B flags kept and -X left as the maintainers set it, and both steps get shell: bash so the same line runs on the Windows leg of the matrix, where the default shell is PowerShell; cifuzz.yml and codeql.yml get the same change where they invoke Maven. The README's build instructions, which today say to add jsoup to a Maven or Gradle build rather than how to build the project itself, get one line naming ./mvnw verify. The wrapper downloads its distribution into ~/.m2/wrapper/dists, which is outside the ~/.m2/repository directory that cache: 'maven' on actions/setup-java keeps, so the agent adds an actions/cache step for ~/.m2/wrapper keyed on the properties file, and the download happens once per cache key rather than once per job.

To check it, the agent runs ./mvnw -v in its sandbox, which downloads the distribution and prints the pinned Maven version and the JDK, then ./mvnw -B -DskipTests compile so the multi-release compilation runs under the pinned Maven, and finally ./mvnw -B verify with the project's own surefire and failsafe configuration. It deletes ~/.m2/wrapper and runs ./mvnw -v once more to show the checksum verification on a fresh download, and it runs mvnw.cmd through cmd.exe if Wine is available or, if not, says in the pull request that the Windows script was generated by the plugin and not executed.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add the Maven Wrapper to this project. Read pom.xml for the plugins and any Maven version requirement, every workflow under .github/workflows that runs mvn, .gitignore, .gitattributes and the README. Generate the wrapper with mvn -N wrapper:wrapper, choosing the newest Maven release the project's plugins support and the only-script distribution type, add the distribution's published SHA-256 checksum to .mvn/wrapper/maven-wrapper.properties, and mark mvnw executable in git. Change every mvn invocation in the workflows to ./mvnw, keeping the existing flags, and add a build line to the README. Run ./mvnw -v, ./mvnw compile and ./mvnw verify, clear the wrapper's download cache and run ./mvnw -v again to show the checksum check, and open a pull request with the commands and their output.",
  "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 adds mvnw, mvnw.cmd and .mvn/wrapper/maven-wrapper.properties, changes the Maven lines in each workflow and the README, and leaves pom.xml as it was. Its description names the Maven version pinned and why, quotes the ./mvnw -v output showing that version downloaded and verified, and shows the end of the verify run so a reviewer can see the project's own tests pass under the pinned Maven.

A reviewer checks the distributionUrl and checksum against Apache's download page, confirms the executable bit on mvnw in the diff, and looks at the Windows leg of the next workflow run. After merging, every contributor and every CI runner builds with the same Maven, and bumping Maven is a one-line change to the properties file that CI tests like any other.

Run it on every Maven project in the terminal

A developer with mvn in their history sends this body from their own machine with the repository in resources and reads the pull request from the console when the webhook on their API key reports the run. An organisation with many Maven repositories sends one request per repository, each with a request_id that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own POM: a project whose POM already names a minimum Maven through the enforcer plugin gets a wrapper pinned at or above it, and a project whose workflows already use ./mvnw gets only the checksum and the executable bit if they are missing.

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

Why run it on Rush?

The wrapper is five minutes of work and one easy mistake: a checksum left blank, a mode bit dropped, a workflow still calling mvn, a Windows script with the wrong line endings. The agent generates it with Maven's own plugin in its own sandbox, builds the project through it from a cold cache, and keeps every command and its output in the run's record, so the pull request shows the download, the verification and the build rather than describing them.

It also reads the project it is in: the plugin versions that bound which Maven to pin, the eol=lf rule in .gitattributes that keeps the script runnable, the setup-java cache that already covers the wrapper's download directory. Twenty repositories with twenty POMs get twenty pull requests, each pinned to a version that builds that project.

Frequently asked questions

Which Maven version does it pin?

The newest release the project's plugins support, which it reads from the POM and the plugins' documented requirements. The pull request says which version it chose and why, and the version lives in one line of .mvn/wrapper/maven-wrapper.properties so it is easy to change.

Does it commit a jar?

No. The only-script distribution type writes two scripts and a properties file, and the scripts download the Maven distribution on first use. The agent adds the distribution's SHA-256 checksum so the download is verified, which is what makes the wrapper safe to run on a CI runner.

Will CI get slower?

The first run on a fresh runner downloads the Maven distribution once, and the agent adds a cache step for the wrapper's download directory keyed on the properties file, so later runs reuse it. The build itself is unchanged.

What about Windows contributors?

The plugin generates mvnw.cmd alongside mvnw, and the agent keeps the repository's existing line-ending rule so both scripts check out runnable. The pull request says whether the Windows script was executed in the sandbox or only generated.

More Maven jobs

More jobs like this: Hand off a long task

Keep reading