Skip to end of metadata
Go to start of metadata


This page documents the OPS4J release process for those OPS4J members that are able to release OPS4J artifacts, such as Alin Dreghiciu, Niclas Hedhman, Toni Menzel, Harald Wellmann and others.


The OPS4J release process is based on the Maven Release Plugin and Sonatype OSS Repository Hosting which enables us to push all OPS4J artifacts to Maven Central. You need to sign up with Sonatype, read their Usage Guide and get familiar with the Maven Release Plugin before doing your first release.

After signing up, create a ticket in OSSRH JIRA to have your account added to the org.ops4j group to get permissions for the org.ops4j staging repositories.

Then you need to generate a GPG key and set up your GPG passphrase and your Sonatype credentials in your Maven settings.xml. See Appendix B and Appendix C for details.

Before releasing

Before starting the release process ensure that:

  • Your Git workspace has no uncommitted changes.
  • There are no snapshot dependencies in the project to be released
  • Ensure that your main project pom inherits from OPS4J master pom, at least version 4.0.0:

  • Your main pom project defines an <scm/> section as below, replacing PROJECT by your actual project name.

  • Make sure your shell can push to GitHub without password prompts, see Appendix D.

There used to be another master POM org.ops4j.pax:master for Pax projects which is now obsolete as all definitions in org.ops4j:master apply to Pax and non-Pax projects alike.

Prepare the release

From a command line run the following:

mvn release:prepare

Perform the release

From a command line run the following:

mvn release:perform

Once you are familiar with this procedure, you can combine prepare and perform in one step:

mvn release:prepare release:perform

Doing the two steps separately may help you to troubleshoot problems and rollback.


If the release builds fails, you'll have to revert to a pre-release state before trying again. mvn release:rollback or mvn release:clean may help sometimes, but not always.

Make sure that all POMs have SNAPSHOT versions and that the release tag is not set in your Git repository. Use git tag -d myproject-1.2.3 to delete the tag if needed. If the tag has already been pushed to GitHub, use git push origin :refs/tags/myproject-1.2.3 to delete the remote tag after deleting it locally.

Push to Maven Central

The master POM includes the nexus-staging-maven-plugin which is configured to close the staging repository on Sonatype OSS Nexus automatically. It will not automatically release the staging repository, to give you and others a chance to test the staged release before publishing it.

To push the released artifacts to Maven Central, run the following commands:

cd target/checkout
mvn nexus-staging:release

A cron job will push the artifacts to Maven Central within a few hours.

Alternatively, you can log in to Sonatype OSS Nexus to release or to drop the staging repository interactively.


In the admin section of the released project use the "Release" button to mark the version as released and create the next version. Then close all issues related to just released version using a comment as "Released under x.y".

Change log

Create a change log in the Confluence wiki space of your project. Here is an example from Pax Web. You can include an auto-generated JIRA report of all issues closed for the given releases using the {jiraissues} macro.

Blog entry

Create a Confluence blog entry announcing the release. The announcement should explain the release highlights and a may include a link to change log created in the step above.
Here is an example from Pax Exam.

Make sure to add the labels release and <project name>. This will make your blog entry appear on the OPS4J overview page and on the project homepage by means of a Confluence macro. Check the Pax Exam homepage for an example.

Release announcement

Send a release announcement to and

Appendix A: Maven Profiles

As of org.ops4j:master:3.0.0, you no longer need to enable specific Maven profiles for a release.

Appendix B: Authentication

While deploying the artifacts to the specified repositories Maven will use credentials specified in ~/.m2/settings.xml.

Sonatype Nexus authentication

To deploy to Sonatype repositories you will need an account for which you will get an name/password pair. If you do not have an account, sign up with [Sonatype JIRA|JIRA task] and create an issue to have your account added to the org.ops4j.* group.

The JIRA credentials also given you access to the OSSRH Nexus web interface.

Add these credentials to your settings.xml:

      <username> <!-- your user --> </username>
      <password> <!-- your password --> </password>

Appendix C: Signing key

We are using GnuPG for signing the artifacts via Maven gpg plugin, this is a requirement of the Sonatype OSS release process.

Generate the private/public key pair

On *nix run the code below and follow the instructions:

gpg --gen-key

We suggest that:

  • when gpg asks for e-mail linked to the key you should use the e-mail that you use on the mailing lists
  • when gpg asks for comment linked to the key you should use "CODE SIGNING KEY"

If gpg --gen-key appears to hang and complains about missing entropy, open another shell on the same machine and run some disk-bound command like ls -lR /.

Specify your GPG passphrase

At some point in a release build, GPG requires your passphrase, prompting for it on the command line by default. To avoid this prompt, define the following profile in your Maven installation settings $MAVEN_HOME/conf/settings.xml:

      <!-- Do not change this profile ID -->
        <gpg.passphrase> <!-- your key passphrase --> </gpg.passphrase>

Make sure to include this profile in your Maven installation settings, not in the user settings under ~/.m2. This is because the Maven Release plugin disables all profiles from user settings.

Note that you can also provide the pass phrase via command line:

mvn release:perform -Darguments=-Dgpg.passphrase=YOURPASSPHRASE

Appendix D: GitHub access

If your Git workspace is configured to use SSH, make sure that you have an ssh-agent running and call


in your shell before running the Maven Release plugin to avoid prompts during the release process.

Alternatively, if you use HTTPS authentication, specify your credentials via properties when running the Maven Commands:

mvn ... -Dusername=... -Dpassword=...  release:perform
  • No labels