Publish open source project to Maven with Sonatype

Introduction

In this article, we are going to see step by step how to publish your project to Maven and make it accessible to everyone. I found a lot of interesting articles but none seem up to date or explain step by step.

Definitions

• GroupId: is the first block in the Maven dependency.
• Organization: is the same as groupId, in the sbt build file.
• Username: is the username you have under sonatype website, is not involved in the library name once published.
• Project name: is the middle part of the Maven dependency
• Artifact name: is the same as the project name.

Useful links

• Jira Sonatype dashboard
• Sonatype Web UI
• Official Sonatype documentation
• Maven Search
• How long does Sonatype staging take to sync my artifacts with Maven central on Stackoverflow
• SBT Plugin to deploy to Sonatype
• Sonatype online file browser:
  • Snapshots
  • Staging
  • Releases
• All my issues about deploying:
  • Issue #44 on sbt-ci-release
  • Question on Reddit
  • Question with Bounty on Stackoverflow
  • Question on Sonatype’s Community website
  • Ticket on Sonatype’s Jira

How to publish using Sonatype step by Step

First, Create a jira account for Sonatype and Create an issue

1. Sign up to the Jira for Sonatype at this link: https://issues.sonatype.org/secure/Signup!default.jspa
2. Go to the Dashboard page
3. Click Create in the top of the page

Fill up the issue modal form

1. “Summary“:
   1. “Create new project <project name>”
2. “Description“:
   • “Hello, I would like to create a new open source project with the name <project_name> under the group Id <group_id>.
     Here are the relevant links:
     * <links to your github repo>
     * <links to your own domain>
     “
3. “Group Id“:
   1. Your domain name, ie: com.leobenkel
   2. if you don’t own a domain:
      1. com.github.<git_username>
4. “Project URL“:
   1. Either:
      1. Git repo link
      2. Official webpage of your project
5. “SCM url“:
   1. The clone HTTP Github repo link
   2. it should end by .git.
6. “username“:
   1. the username you used to create your account in the previous step
7. Already synced to central
   1. No

Example of what your issue can look like

I submitted a first one to get my domain authorized: https://issues.sonatype.org/browse/OSSRH-48700. Make sure that your website have a link pointing to your GitHub account, which I added on this page.

And then I opened one to authorized my project: https://issues.sonatype.org/browse/OSSRH-49305. Which happened to be not necessary. So do not do the same mistake I made! You only need one ticket per GroupId.

Build.sbt

In your build files you need to add:

• organization which would correspond to the GroupId you set up in Sonatype.
• name which would correspond to the project name or artifact name.
• homepage which would correspond to “Project URL” or “SCM url” when you opened up the Jira ticket earlier.
• licenses is up to you but I would advise to use MIT, but don’t trust me and look it up for yourself at: Open Source Initiative website.
• developers is a List of the case class Developer. It contains:
  • username correspond to the “username” in the sonatype jira ticker
  • First and last name
  • email which I personally did not put. I don’t feel good about having an easily parsable email online
  • website which is the personal website of this developer

Let Travis submit your project to Sonatype for you

I assumed that you have already read Travis-continuous deployment and your project is already built using Travis.

Install sbt-ci-release

I would advise to just follow the README over there. But I will just repeat the outline of what you have to do so you can follow along.

First, add the plugin to your project with:

addSbtPlugin("com.geirsson" % "sbt-ci-release" % [VERSION])

Go to https://github.com/olafurpg/sbt-ci-release/blob/master/readme.md#sbt to get the correct version.

For an example you can look at https://github.com/leobenkel/safety_plugin/blob/25539b632bf885734cda0156f01f44b25fdd96b9/project.sbt#L3-L13.

GPG

This step was the most scary to me but I followed the README on sbt-ci-release plugin page and it was pretty straightforward.

I ended up with a working deploy pipeline through Travis. But locally I get an exception :

[error] java.io.IOException: secret key ring doesn't start with secret key tag: tag 0xffffffff

When I do sbt publishSigned.

I installed gpg using brew which might be the cause. I found this https://github.com/sbt/sbt-pgp/issues/123 which seem to say to NOT use the brew version.

At the end of the day, I don’t need to deploy a release version from my local machine so I did not bother digging deeper into it. If you have a solution, feel free to add a comment below and I’ll update this article to help others.

Setup Travis environment variables

Once all of that is done, you need to add the environment variables to your Travis pipeline.

1. Go back to Travis Dashboard.
2. Click on your repo
3. On the right of the UI, you should have a button “More options”, click on it
4. Then “Settings” from the drop down menu
5. Scroll down to “Environment Variables”
6. Follow the README from sbt-ci-release
7. Make sure “Display value in build log” is OFF
8. You need 4 new variables:
   • PGP_PASSPHRASE : The password you used in the GPG step to create the key
   • PGP_SECRET : The secret part of your GPG key. The readme has command line to get it.
   • Sonatype:
     1. The first step is to create your “Access User Token” as explained https://github.com/olafurpg/sbt-ci-release/blob/master/readme.md#optional-create-user-tokens.
     2. You will end up with a pop up with some characters : and some more characters.
     3. The left part is the username part and is used for the env var SONATYPE_USERNAME
     4. The right part is the password and is used for the env var SONATYPE_PASSWORD

You should end up with something like that in your Travis Settings UI:

Setup .travis.yml

Now you need to tell Travis build pipeline to release your project when you merge new code

You will need to add

before_install:   
    - git fetch --tags

And then add a Stage release with an if condition:

stages: 
 - ...other stages...
 - name: release
   if: ((branch = master AND type = push) OR (tag IS present)) AND NOT fork

And then define the Job of this Stage:

 jobs:
   include:
     - ...other stages...
     - stage: release
       name: release
       script: sbt ci-release

And that is it for the .travis.yml config file. Feel free to take a look at my .travis.yml as an example.

With those settings, every time you are going to merge a commit to master, a release is going to be pushed as snapshot.

Publish release version

To publish a release version, you will have to execute some more commands.

git tag -a $VERSION -m $VERSION
git push origin $VERSION

The version will be the version that is being deployed to the release repo of Sonatype.

BE CAREFUL!

The $VERSION needs to start by v , for instance 0.1 will not work but v0.1 will !

Now, we wait

Once you have tagged a commit and pushed it to master, a release will be deployed. You then needs to wait for Maven to pick up the change. According to Sonatype documentation, it should take about 10min but I had to wait more like 40min so don’t get too impatient ! For the Maven Search, it takes up to 2 hours to pick up the change.

Conclusion

So now you should be able to publish your awesome open source library ! Feel free to share your repo in the comments for people to see !