Deploying to Maven’s Central Repository

You have a new open source library that you’d like to share with the world? Downloading a dependency from Maven is simple but adding your artifacts to the Maven Central Repository can be a daunting task. At Pleo we recently went through this and decided to share this precise and simple step by step guide.

High level overview

These steps are required ONCE. After that, it’s a lot simpler. From a high level view, we’ll need to do the following:

  1. Create a Sonatype OSSRH account
  2. Ensure your library is properly configured
  3. Deploy

1. Create a Sonatype OSSRH account

Sonatype OSSRH (Open Source Repository Hosting) is a Maven repository that can easily sync with the Maven Central Repository. We will first deploy our artifacts into Sonatype OSSRH and then ask them to sync with the Maven Central Repository.

Sign up for Sonatype’s JIRA

We recommend you create a company account. We used a shared email.

Create a New Project ticket

The title doesn’t seem very important but the required fields are. You can use our first JIRA as an example.

While you wait for the ticket to be processed, you can keep moving ahead with the next steps.

2. Ensure your library is properly configured

This is the longest section but it’s not as bad as it looks. It’s a lot of copy pasting and running commands but it doesn’t take long and there’s nothing complicated.

We’ll use Maven but you can use another tool (Gradle, SBT,...).

The full list of requirements is available on Sonatype’s site. This page is a summary of the full Apache Maven instructions.

Make sure your version number is not a SNAPSHOT version. Only final (non-snapshot) versions can be deployed.

We’ll add information to our pom.xml. If you have multiple modules, we recommend that you use a parent pom which will be shared across your modules.

Of course you need to replace the information in this snippet with your company’s information. Don’t forget to change the license if you’re not using the MIT license.

We also need to add various Maven plugins

This does a lot of different things

  1. Setup maven-source-plugin to ensure that sources are always attached to your build. This is useful even if you don’t publish to the Maven Central Repository so it is not in any special profile.
  2. Create a profile called release which will contain plugins only required when releasing a new version of your library.
  3. Add maven-javadoc-plugin to ensure that javadoc is attached to your artifacts. This is required by the Maven Central Repository.
  4. Add maven-gpg-plugin to ensure that your artifacts are signed. This is required by the Maven Central Repository.
  5. Add the nexus-staging-maven-plugin. This is a nice utility plugin that makes things simpler when deploying to the Maven Central Repository through Sonatype’s OSSRH.

Make sure you’re using the latest version of each plugin.

In order to sign your artifacts with maven-gpg-plugin we need to create a GPG key.

  1. Make sure you have GPG installed. On macOS with Homebrew run brew install gpg
  2. Run gpg2 --gen-key . You can keep the default value for everything. Create a passphrase and note it down.
  3. gpg2 --gen-key will output something like this pub 2048R/3A730BC 2017–01–27 The part after the slash ( 3A730BC ) is your key ID. Note it down.
  4. Run gpg2 --keyserver hkp:// --send-keys YOUR_KEY_ID . This will distribute your key so that everyone (including OSSRH) can validate your signature.

In your Maven settings.xml (default location ~/.m2/settings.xml ) add the following:

This will ensure that mvn can deploy to OSSRH and will ensure that mvn-gpg-plugin knows where to find gpg and what your passphrase is.

3. Deploy

It’s been a long road but we’re nearly there.

By now, your OSSRH Jira should have received an answer telling your that you can now deploy and to comment once you’ve done so.

You can now run mvn clean deploy -Prelease . This will run the deploy command using the Maven profile named release which we created earlier.

Hopefully this works smoothly! Once you’re done deploying, you can simply go to the OSSRH Jira and ask them to sync to the Maven Central Repository!

That’s it!

The next time you want to deploy something, you will only need to to run mvn clean deploy -Prelease !

Sharing information with your colleagues

You’ve created a few things that now need to be shared with your coworkers.

  • The OSSRH Jira user and password
  • The GPG passphrase
  • The GPG secret

To share the GPG secret, simply run gpg --export-secret-key -a > secretkey.asc , send the file to your coworkers and have them run gpg --import secretkey.asc .

We use 1Password to share all of these sensitive items.

The End?

Hopefully this guide saves you some of the troubles we’ve encountered while setting up our integration with the Maven Central Repository!

If you want to work with the fine people that have created this guide, we’re hiring! Pleo is a company payment card that does your expense reports and simplifies company spending. We love sharing!