# 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 Rush](https://cloud.getrush.ai/run/add-maven-wrapper/maven/). Opens 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`

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

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

- [Add Mutation Testing to a Maven Project](https://getrush.ai/run/add-mutation-testing/maven/)
- [Add OWASP Dependency-Check to a Maven Build](https://getrush.ai/run/add-owasp-dependency-check/maven/)
- [Add PMD Static Analysis to a Maven Build](https://getrush.ai/run/add-pmd/maven/)

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

- [Make GitHub Actions Workflows Run in a Merge Queue](https://getrush.ai/run/add-merge-queue-support/github-actions/)
- [Add Mermaid Diagrams to a Docusaurus Site](https://getrush.ai/run/add-mermaid-diagrams/docusaurus/)
- [Add Mermaid Diagrams to an Eleventy Blog](https://getrush.ai/run/add-mermaid-diagrams/eleventy/)

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