# Add a Release Workflow for a Maven Library

Yes. An agent adds a tag-triggered GitHub Actions workflow that signs and publishes your Maven library to Maven Central and drafts the GitHub release.

[Run this on Rush](https://cloud.getrush.ai/run/add-release-workflow/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 library is built and how it has been published so far. In a library laid out like jhy/jsoup, `pom.xml` is `org.jsoup:jsoup` at `1.24.2-SNAPSHOT`, with `<scm>` pointing at the GitHub repository, `maven-source-plugin` and `maven-javadoc-plugin` executions that attach the sources and Javadoc jars, a `bundle-manifest` execution for OSGi metadata, `japicmp-maven-plugin` 0.26.5 comparing against the previous release, `maven-release-plugin` 3.3.1, and already the `org.sonatype.central:central-publishing-maven-plugin` at 0.12.0 with `<publishingServerId>central</publishingServerId>`. A `release-sign-artifacts` profile runs `maven-gpg-plugin` in the `package` phase when `performRelease` is `true`, but the plugin has no version in the POM. Tags follow `jsoup-1.24.1`, `CHANGES.md` opens each release with a heading such as `## 1.24.1 (2026-Nov-03)`, and `README.md` links the latest tag's GitHub release. `.github/workflows/` has `build.yml` running `mvn verify` on JDK 8, 17 and 25 across three operating systems, `codeql.yml` on JDK 17 and `cifuzz.yml`; nothing publishes, so every release so far has run `mvn deploy` from a maintainer's machine.

The workflow the agent adds, `.github/workflows/release.yml`, runs on `push` of a tag matching `jsoup-*` and on nothing else, so a tag is the release decision. Its job checks out the tag, calls `actions/setup-java` at its current major with JDK 17 and `cache: maven`, because the POM's `multi-release` profile needs JDK 11 or later to assemble the multi-release jar and `codeql.yml` already builds on 17, and passes `server-id: central` with `server-username-env-var: MAVEN_USERNAME` and `server-password-env-var: MAVEN_CENTRAL_TOKEN`, which makes the action write a `settings.xml` whose `central` server reads those two environment variables, matching the `publishingServerId` the POM already names. The deploy step is `mvn -B -DperformRelease=true -Dgpg.signer=bc deploy`, where `performRelease` activates the signing profile and `gpg.signer=bc` tells the GPG plugin to sign with its Bouncy Castle signer from the `MAVEN_GPG_KEY` and `MAVEN_GPG_PASSPHRASE` variables rather than a `gpg` binary and keyring on the runner. The agent pins `maven-gpg-plugin` to 3.2.8 in the profile, since the Bouncy Castle signer needs 3.2.0 or later and the POM's unversioned plugin would resolve whatever Maven's defaults chose.

Four repository secrets hold the credentials: `MAVEN_USERNAME` and `MAVEN_CENTRAL_TOKEN`, the user token pair from the Central Portal, and `MAVEN_GPG_KEY` with `MAVEN_GPG_PASSPHRASE`, the ASCII-armoured secret key and its passphrase. The workflow reads them from a GitHub environment named `release`, so the repository's protection rules can require a reviewer before the job runs. The plugin's default `waitUntil` is `validated`, so the job ends once the Portal has checked the bundle and a maintainer presses publish there; the agent leaves `autoPublish` off and documents the one line that turns it on. A guard step compares the tag to the POM: it reads `project.version` with `mvn help:evaluate` and fails when the tag is `jsoup-X` but the version is `X-SNAPSHOT`, which is the mistake a tag pushed before `release:prepare` produces.

After the deploy, a step extracts the section of `CHANGES.md` whose heading starts with the tag's version and creates the GitHub release with `gh release create` using that text as the body and the built jar attached, under `contents: write` permission, which is how the README's link to the latest release gets a target. The agent cannot run a deploy in its sandbox, since it has no Portal token or signing key, so it checks what it can: `actionlint` on the workflow, a dry `mvn -B -DperformRelease=true -Dgpg.skip verify` on JDK 17 to confirm the profile and the version guard behave, and `mvn help:evaluate -Dexpression=project.version` to show the guard's input.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add a release workflow for this Maven library. Read pom.xml (the plugins, the release-sign-artifacts profile, the central-publishing-maven-plugin configuration and the multi-release profile), CHANGES.md, README.md and every file under .github/workflows first, and check the tag naming in the repository's existing tags. Add .github/workflows/release.yml that runs on tag pushes matching the existing tag pattern, uses actions/setup-java at its current major with JDK 17 and server-id matching the POM's publishingServerId with username and password environment variables, fails when the tag's version does not equal project.version, runs mvn -B -DperformRelease=true -Dgpg.signer=bc deploy with MAVEN_USERNAME, MAVEN_CENTRAL_TOKEN, MAVEN_GPG_KEY and MAVEN_GPG_PASSPHRASE from a release environment, then creates the GitHub release with the matching CHANGES.md section as its body and the jar attached. Pin maven-gpg-plugin to a version that supports the Bouncy Castle signer. Do not add autoPublish; document it. Run actionlint, run mvn verify with the release profile and gpg.skip on JDK 17 to check the profile, and open a pull request that lists the four secrets to create and says no deploy was made.",
  "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 `.github/workflows/release.yml` and changes one line of `pom.xml`, the `maven-gpg-plugin` version in the signing profile. Its description names the four secrets and the `release` environment to create, quotes the `actionlint` result and the `mvn verify` run with the signing profile active and GPG skipped, shows the version guard's two cases, and states that nothing was deployed and no tag was pushed.

A reviewer checks the tag pattern against the repository's tags, decides whether the `release` environment should require a reviewer, and whether to keep the Portal's manual publish step or set `autoPublish`. The first real release is the usual `release:prepare` followed by pushing the tag, and the Actions log is where the Portal's validation result appears.

`build.yml`, `codeql.yml` and `cifuzz.yml` are untouched, and the POM's artifact set, the sources, Javadoc and OSGi manifest, is what the workflow uploads.

## Run it on every library without a release workflow

An organisation that publishes several Maven libraries can send this body once per repository from a short script on its own server: list the repositories the GitHub App reaches with `GET /o/{org}/github`, keep those whose default branch has a `pom.xml` and no workflow with a `tags:` trigger, and give each request a `request_id` that is a UUID v5 of the repository's full name so a rerun returns the runs it already started. Each run opens one pull request fitted to that POM's plugins and tag names, and the key's `webhook_url` receives `run.completed` for each.

Once the workflow is in, an automation on the Project with a `github` trigger on `workflow_run.failure` can run read-only with a prompt that reads the failed release job's log and comments on the commit with the Portal's validation message or the guard's version mismatch. The trigger adds the event after the prompt; it fills in no placeholder.

## Why run it on Rush?

A release workflow is where a library's build, signing and publishing meet, and each has a rule that is easy to get wrong: the `settings.xml` server id must match the POM's `publishingServerId`, the GPG plugin's Bouncy Castle signer needs a version the POM did not pin, the multi-release jar needs a JDK the test matrix only partly uses, and a tag pushed against a snapshot version publishes nothing useful. The agent reads the POM as it is, writes the workflow around the plugins already there, and runs the checks that need no secret in its sandbox, with the output kept in the run's record.

It also keeps the secrets where they belong. No token or key enters the run; the pull request names the four secrets and the environment, and a maintainer creates them, which is the division of labour a signing key deserves.

## Frequently asked questions

### Does the workflow run the maven-release-plugin?

No. `release:prepare` edits the POM, commits and tags, which stays a maintainer's step on their machine, as it is today. The workflow starts when that tag is pushed, checks that the tag's version equals `project.version`, and runs `mvn deploy`, so the version bump and the publish are two steps a person can see separately.

### Why gpg.signer=bc?

The Bouncy Castle signer in `maven-gpg-plugin` 3.2.0 and later reads the key from `MAVEN_GPG_KEY` and the passphrase from `MAVEN_GPG_PASSPHRASE` and needs no `gpg` binary, keyring or agent on the runner. The POM's profile had no plugin version, so the agent pins 3.2.8 to make the signer available.

### Who publishes on the Central Portal?

With the plugin's default `waitUntil` of `validated`, the job uploads the bundle, waits for the Portal to validate it, and ends; a maintainer presses publish in the Portal. Setting `autoPublish` to `true` in the plugin configuration makes the job publish as well, and the pull request shows that line without applying it.

### What if the tag does not match the POM version?

A guard step reads `project.version` with `mvn help:evaluate` and fails the job before anything is signed or uploaded when the tag is `jsoup-1.25.1` but the POM says `1.25.2-SNAPSHOT`, printing both values. That is the state a repository is in when a tag is pushed before `release:prepare`.

### Why JDK 17 for the release build?

The POM's `multi-release` profile assembles the Java 8 base and the Java 11 overlay into one jar only when the build runs on JDK 11 or later, and the repository's `codeql.yml` already builds on 17. Building the release on 8 would publish a jar without the overlay, so the workflow uses 17 and the tests on 8 stay in `build.yml`.

## More Maven jobs

- [Make a Maven Build Reproducible](https://getrush.ai/run/add-reproducible-builds/maven/)
- [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/)

## The same job on other stacks

- [Add a GitHub Release Workflow to an Obsidian Plugin](https://getrush.ai/run/add-release-workflow/obsidian-plugin/)
- [Add a Release Workflow for a Textual App](https://getrush.ai/run/add-release-workflow/textual/)
- [Add a Release Workflow With Prebuilt Binaries to a Tokio Server](https://getrush.ai/run/add-release-workflow/tokio/)

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