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:
- Create a Sonatype OSSRH account
- Ensure your library is properly configured
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.
We recommend you create a company account. We used a shared email.
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,...).
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
maven-source-pluginto 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.
- Create a profile called
releasewhich will contain plugins only required when releasing a new version of your library.
maven-javadoc-pluginto ensure that javadoc is attached to your artifacts. This is required by the Maven Central Repository.
maven-gpg-pluginto ensure that your artifacts are signed. This is required by the Maven Central Repository.
- 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.
- Make sure you have GPG installed. On macOS with Homebrew run
brew install gpg
gpg2 --gen-key. You can keep the default value for everything. Create a passphrase and note it down.
gpg2 --gen-keywill output something like this
pub 2048R/3A730BC 2017–01–27The part after the slash (
3A730BC) is your key ID. Note it down.
gpg2 --keyserver hkp://pool.sks-keyservers.net --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.
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!
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.
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!