# Make a Maven Build Reproducible

Yes. An agent sets project.build.outputTimestamp, upgrades the plugins check-buildplan names, proves two builds match with artifact:compare, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-reproducible-builds/maven/). Opens 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 changes it. In a library laid out like jhy/jsoup, `pom.xml` is a single module at version `1.24.1-SNAPSHOT` with `project.build.sourceEncoding` as its only build property and no `project.build.outputTimestamp`. The build is more than a plain jar: `maven-compiler-plugin` `3.16.0` compiles a Java 8 base and, on JDK 11 and newer, a Java 11 overlay into a multi-release jar; `animal-sniffer-maven-plugin` `1.28` checks the Java 8 and Android API surfaces; `maven-bundle-plugin` `5.1.9` writes the OSGi manifest; `maven-jar-plugin` `3.5.1`, `maven-source-plugin` `3.4.0` and `maven-javadoc-plugin` `3.12.0` package the artifacts; `maven-release-plugin` `3.3.1` and `central-publishing-maven-plugin` `0.11.0` publish them; `japicmp-maven-plugin` `0.26.3` compares the API against the previous release; and a `java-8` profile swaps in older configuration when the JDK is 8. `.github/workflows/build.yml` runs `mvn -X compile` and `mvn -X verify` on Ubuntu, Windows and macOS with JDK 8, 17 and 25 from Zulu, and `dependabot.yml` bumps Maven plugins weekly. There is no Maven wrapper, so the runner's Maven decides the default behaviour.

The first change is the property: `<project.build.outputTimestamp>` set to an ISO 8601 UTC instant in `<properties>`, which every reproducible-aware plugin reads for file timestamps inside jars and for manifest dates. The agent then runs `mvn artifact:check-buildplan`, which walks the build plan and names any plugin whose version is known not to honour the property, and bumps exactly those in `pom.xml`, reading each plugin's release notes rather than jumping to the latest. Two places need a look beyond the plan: the bundle plugin's manifest, where the agent builds once and checks that `MANIFEST.MF` carries no wall-clock header such as `Bnd-LastModified`, and the javadoc jar, whose content is tied to the JDK that generates it, which the pull request records as a constraint rather than a defect.

Proof is two builds compared, not a claim. The agent runs `mvn -B clean install` on JDK 17, then `mvn -B clean verify artifact:compare`, which rebuilds and compares every attached artifact against the installed one and writes the result to `target/`; a `ko` count above zero means something still varies. When it does, `mvn artifact:buildinfo` prints the `diffoscope` command for the pair and the agent runs it to find the unstable file, usually a timestamp or an absolute path, and fixes the plugin configuration that produced it. It repeats the pair on JDK 8 under the `java-8` profile, since the multi-release layout changes which classes are compiled there, and confirms the comparison is clean on each JDK on its own, not across them.

The CI workflow gains a `reproducible` job on `ubuntu-latest` with JDK 17 that runs `mvn -B clean install` followed by `mvn -B clean verify artifact:compare` and fails when the goal reports a difference. It is one job rather than nine because the comparison is only meaningful on one JDK major and one line-ending convention at a time, which the pull request spells out. Because `maven-release-plugin` at `3.3.1` rewrites the timestamp in the same commit that sets the release version, no release step changes; the agent adds one sentence to `CONTRIBUTING.md` saying the property is maintained by the release and must not be edited by hand.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Make this Maven build reproducible and open a pull request. Read pom.xml, .github/workflows/build.yml, .github/dependabot.yml and CHANGES.md first. Add project.build.outputTimestamp as an ISO 8601 UTC instant to the properties. Run mvn artifact:check-buildplan and upgrade only the plugins it names, reading each plugin's release notes for the reproducible-builds change. Build once and inspect the jar manifest for wall-clock headers. Run mvn -B clean install and then mvn -B clean verify artifact:compare on JDK 17 and again on JDK 8 under the java-8 profile; where the comparison reports a difference, use the diffoscope command from mvn artifact:buildinfo to find the file and fix the plugin configuration responsible. Add a reproducible job to the build workflow that runs the install and compare pair on one JDK and fails on any difference. Note in CONTRIBUTING.md that the release plugin maintains the timestamp. Open a pull request that lists each plugin upgraded and why, quotes the compare output on both JDKs, and states the JDK and line-ending caveats.",
  "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`, `.github/workflows/build.yml` and `CONTRIBUTING.md`. Its description lists the property it added, each plugin version it raised with the release note that made it reproducible, and the `artifact:compare` summary from the JDK 17 and JDK 8 runs in the sandbox, each ending with zero differences, with the `diffoscope` output for any file that varied on the first attempt and the configuration change that fixed it.

It states the two limits plainly: a jar built on one JDK major does not match one built on another, because the bytecode differs even with the same `--release`, and the javadoc jar follows the JDK that generated it; and a build on Windows differs from one on Linux where line endings leak into resources. The new CI job therefore compares on one platform and one JDK, which the description says is the guarantee being offered.

Before merging, a reviewer checks the timestamp is a UTC instant and not a local time, confirms the plugin bumps are the minimum the build plan asked for, and decides whether to compare against the published artifacts on Maven Central with `-Dreference.repo` at the next release, which is the step that proves reproducibility to someone outside the project.

## Run it on every release tag

Once the build is reproducible, a handler on the reader's server receives GitHub's `release` webhook, which cannot carry a custom `Authorization` header, and calls an automation's `webhook` trigger on the Project with `Authorization: Bearer <its secret>` and the tag name as the text. It sends the delivery id as the trigger's `Idempotency-Key` header, so a redelivery starts nothing new. The automation's prompt, "check out the tag named in the event after this prompt, run mvn -B clean verify artifact:compare with reference.repo set to Maven Central, and open an issue if any artifact differs from what was published", starts one run per release; the trigger puts the tag after the prompt and fills in nothing else, so the run reads the tag from the event and the version from `pom.xml`.

An organisation with several Maven libraries 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 build: a multi-module project gets the property in the parent POM only, and one that already sets the timestamp gets the compare job and the plugin check alone.

## Why run it on Rush?

Reproducibility is proved by building twice and diffing, and the diff is where the work is: a multi-release jar, an OSGi manifest, a javadoc jar and a release plugin each have their own way of leaking a timestamp or a path. The agent runs those builds on two JDKs in its sandbox, reads the `diffoscope` output when they differ, and changes only the plugin configuration responsible, rather than bumping everything and hoping.

The build plan report, the compare summaries and any diff stay with the run, so a reviewer sees which plugin was the problem and that the pair now matches. A team with several Maven libraries sends the same request to each and reads one pull request per repository, each with its own compare output.

## Frequently asked questions

### Why is a single timestamp property enough?

Because the plugins that write archives read `project.build.outputTimestamp` and use it for every entry's modification time and for manifest dates, which is where most variation comes from. The property does not fix a plugin that embeds a build host or an absolute path, which is why the agent compares two builds and reads the diff rather than stopping at the property.

### Will the artifact match one built on a different JDK?

No, and the pull request says so. Each JDK major compiles different bytecode even with the same `--release`, and the javadoc jar follows the generating JDK. The guarantee is that the same source on the same JDK major and platform produces identical artifacts, which is what the CI job checks.

### Who updates the timestamp at release time?

`maven-release-plugin` from `3.0.0-M1` on, and the project is at `3.3.1`, sets it in the same commit that sets the release version. A project with its own release script would need a `versions:set` call from `versions-maven-plugin` `2.9.0` or later, which the description names in case the release process changes.

### Does this change what is published to Maven Central?

The coordinates and contents are the same; only the entry timestamps inside the jars and the manifest dates become fixed. `central-publishing-maven-plugin` and the GPG signing profile are not touched, and `japicmp` still compares the API against the previous release as before.

## More Maven jobs

- [Add an SBOM to CI for a Maven Project](https://getrush.ai/run/add-sbom-to-ci/maven/)
- [Add SpotBugs to a Maven Build](https://getrush.ai/run/add-spotbugs/maven/)
- [Add Spotless Formatting to a Maven Build](https://getrush.ai/run/add-spotless-formatting/maven/)

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

- [Add Request ID Logging to an Actix Web App](https://getrush.ai/run/add-request-id-logging/actix/)
- [Add Request ID Logging to an AdonisJS App](https://getrush.ai/run/add-request-id-logging/adonisjs/)
- [Add Request ID Logging to an aiohttp App](https://getrush.ai/run/add-request-id-logging/aiohttp/)

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