Recently I joined a conversation on Twitter where the OP complained to spending hours to get a brand new computer setup to publish artifacts to Maven Central. The issue stemmed from having PGP signature files moved from one location to another. There are other issues that may arise when uploading artifacts to Maven Central, specially when doing it for the first time. The rules for publishing artifacts are stated here. A common mistake is to omit one of the required POM elements, which will likely trigger a series of back-and-forth revisions until you get it right. This can be frustrating at times, trust me, I’ve been there.
Once you get the first release right things become smoother, or so you think, as the OP found out when his PGP signatures had to be migrated. I must confess I have not encountered that problem because I let Bintray manage syncing all my artifact releases to Maven Central. I’ve set this up so long ago that in my mind it seems trivial now, but what it it’s not? This got me thinking on what steps may seem obvious to me nowadays but may be troublesome to newcomers. This post describes what I did to make it work.
Step 1: Create a Sonatype account
You simply can’t publish to Maven Central without an account. If you want to publish Open Source projects then follow this guide to get your account setup and ready. I can’t stress enough on making sure you follow the guidelines for naming conventions (groupId, domain). When submitting for access (by creating a JIRA ticket) you’ll have to prove you own the domain and groupId. Validation of every request is performed by a human so be polite and patient, it may take a few days or weeks depending on the quality of the input you supply and the amount of tickets they have to work on.
Step 2: Create a Bintray account
This one is a doozy. Go to bintray.com/login and choose the way you want to create an account. Personally I chose signing with GitHub as that allows you to share information between the two services. After all, social coding meets social artifact deployment, eh?
Step 3: Configure GPG Signing
Here you have the choice to use your own GPG signature or let Bintray sign the artifacts for you. Make sure you have a Maven repository associated with your account if you have not one by default. Whichever way you choose to sign artifacts, the official documentation shows you the few steps you have to follow to complete this task.
Step 4: Configure your Project
You must follow the rules to configure the generated POM files, as well as making sure there are matching sources and javadoc JARs for every binary artifact you intend to publish. You also have to configure the gradle-bintray-plugin to upload artifacts as part of the build. Here is where things can deviate a lot, after all every Gradle build is a custom build, isn’t it? But what if this wasn’t the case? What if there was a way to reuse common configuration between plugins while having a structure similar to what the POM file format offers? This is where the Kordamp Gradle Plugin suite comes in. The following snippet shows the minimum configuration required assuming the following settings and defaults
- Your GitHub and Bintray accounts have a matching name: “joecool”.
- The name of your Maven repository on Bintray is “maven”.
A build file like this generates a POM file that follows the Maven Central publication guidelines, sources and javadoc JARs, and few other goodies such as
- Reuses and applies configuration to the Bintray gradle plugin.
- Enriched manifest entries when activating a release.
- Minimum pom.xml and pom.properties in /META-INF/maven/.
- Additional tasks for querying project state such as: extensions, plugins, taskSettings, and more.
Details about the Kordamp Gradle Plugin suite can be found in the guide, there’s more to it such as
- Reuse and configure code quality plugins like
- Aggregated reports for all previously mentioned plugins.
- Aggregated javadoc and source JARs.
- Integration and Functional test support.
- And more!
However if you choose to use a different path for configuring your project, you must make sure the POM is valid, that source and javadoc JARs are part of the publication, and that the bintray plugin has all required settings. One way to check if your POM is valid is to use either the CheckMavenCentral enforcer rule or the pomchecker-maven-plugin. Considering that the project is made with Gradle you’ll face a hard time applying this plugin to the build, however Maven offers a neat feature: you can invoke a plugin on the command line by specifying its GAV coordinates and goal. Thus, once you’ve generated the POM file you only have to invoke the following command in the same directory where the POM resides
$ mvn org.kordamp.maven:pomchecker-maven-plugin:1.0.0:check-maven-central
Step 5: Publishing for the first time
This can only be done once you have been given the green light from Sonatype to start publishing artifacts. They’ll let you know via the JIRA ticket you previously raised. You can issue a release by invoking
gradle -Prelease=true bintrayUpload
Now, the settings shown in the previous step will FAIL the first time you attempt to publish a release, but only to a point. The binaries will be published on Bintray but will fail to be published to Maven Central, for a very good reason: it’s not enough to publish to Bintray, you must also link your binaries to JCenter first!
You can tell if a binary package has been already linked to JCenter or not by looking at the bottom right corner of the package’s page. If you see the JCenter icon then you’re good to go. On the first release however you’ll see a button that opens a request for linking your package to JCenter. This process also involves a human at the other end, thus please be polite and patient once more. Once you’re request is granted you can go back to your package’s page and click on the “Maven Central” link found on top of all versions. This leads you to the following screen
Here you have to enter your Sonatype credentials and click on the Sync button. This operation may take a few minutes or hours, specially on the first sync. But this is the last hurdle and manual step on the Bintray website. Every subsequent release you make via the command line will be automatically published and synced to Maven Central without any other intervention.
Publishing artifacts to Maven Central and Bintray requires following rules to ensure the integrity of the binaries and their provenance, please don’t be discouraged if it takes more time than expected for both Sonatype and Bintray to approve your requests. However once the publication has been automated you’re good to go to publish artifacts any time you see fit.
Keep on coding!