Publish an Open Source Library to mavenCentral

There were (at least) two popular repositories for hosting open source Java libraries: jCenter and mavenCentral. RingCentral Java SDK was hosted by jCenter, but jCenter is going to be sunset. Due to this we have to migrate the SDK from jCenter to mavenCentral. In this article, I will share the experience we had during this migration process.

Code Signing

To publish a library to mavenCentral, we need to code sign it first.

Firstly, add the signing plugin to your build.gradle file:

plugins {
    ...
    id 'signing'
    ...
}

Configure it to sign both source and docs:

But how can we sign if we don’t have a public/secret key pair?

We can generate a PGP key pair here:

Then we download the public key and secret key to local.

Please note that the file name contains the key ID:

Then we need to import the keys to gpg and generate the public key ring:

The key ring file is ~/.gnupg/secring.gpg and we will need it soon.

Add the following content to gradle.properties file:

signing.keyId=0xDF7B5AA4
signing.password=xxxxxx
signing.secretKeyRingFile=/Users/tyler.liu/.gnupg/secring.gpg

In the configuration above, we specified the keyId, passphrase and the key ring file. All of them are from the previous steps we just performed.

The last step is to upload our public key to a public server. I chose to upload it to https://keys.openpgp.org/upload:

That’s it for code signing, but before we release the library, gradle will automatically do the signing.

Publish to s01.oss.sonatype.org

You need to have a JIRA account from SonaType. If you don’t have one, register here.

Then you need to create new project request ticket, you can take my ticket as an example: https://issues.sonatype.org/browse/OSSRH-67343

Only one JIRA issue per top-level groupId is necessary.

So you don’t need to create a JIRA ticket if you or your organization have created one in the past for the same groupId.

Someone will reply and grant you permission to deploy to the Group Id you specified in the ticket. Once you get the permission, you are good to go.

Update your build.gradle file and add the maven plugin:

plugins {
    ...
    id 'maven'
    ...
}

Please note that the maven plugin is a legacy one which doesn’t work with gradle 7.x.

I had to downgrade gradle to 6.x in order to finish the migration. But I think things will change soon as gradle 7.x becomes more and more popular. There will be ways to proceed without the maven plugin. But for now, we just go with the maven plugin.

Create the uploadArchives task:

And specify the following credentials in gradle.properties file:

ossrhUsername=tylerliu
ossrhPassword=xxxxxxx

The credentials are the ones that you used to login to https://issues.sonatype.org/.

Then we run the following command to upload it to https://s01.oss.sonatype.org:

./gradlew uploadArchives

If everything goes well, you should be able to find the artifacts you uploaded online:

You need to first “Close” it. The word “close” here is kind of confusing. I think it just means “verify”. If verify fails, you will be able to find detailed information in the “Activity” tab. Fix any issues until you are able to “close” it successfully. I didn’t take a screenshot before I closed it. So the screenshot above shows that the repository has been closed already.

Then we click the “Release” button to release it. If everything goes well, your project will disappear from the staging list. And you should be able to search to find it as I did in this page: https://s01.oss.sonatype.org/#nexus-search;quick~ringcentral.

Last but not least, don’t forget to post a comment to your jira ticket, so that your library will be synced to mavenCentral:

References

Although I tried to cover all the tricky parts of publishing an open source library to mavenCentral. There could be important details that I didn’t cover. If you run into any issues and you can’t find an answer from this article, here are more resources you can use:

1. RingCentral Java SDK, its build.gradle file contains lots of useful information
2. How to Publish Your Artifacts to Maven Central. I did learn a lot from this article. It is using maven instead of gradle, so it could be very useful for those who are also using maven.
3. Official publish guide from SonaType. Don’t forget to check this one if you are stuck.
4. Official release guide from SonaType. It contains some screenshots to teach you how to release your project via GUI.

Summary

OK, that concludes this article. I tried to showcase the migration process as detailed as possible on what I did to publish the RingCentral Java SDK to mavenCentral. Especially how to do code signing and how to utilize SonaType. I also include some resources for your reference. Please let us know what you think by leaving your questions and comments below. To learn even more about other features we have make sure to visit our developer site and if you’re ever stuck make sure to go to our developer forum.

Want to stay up to date and in the know about new APIs and features? Join our Game Changer Program and earn great rewards for building your skills and learning more about RingCentral!