This post is the second part of the series “2:20 to Maven Central” – the complete guide to deploying artifacts to Maven Central.
In the previous post, we looked at how to prepare and verify your luggage (a.k.a the POM file). The next step on the way to Maven Central is verifying your identity.
You verify your identity by signing your artifacts and publishing your public key to a public PGP key server. Signing your artifacts is a requirement for publishing them to Maven Central. This is typically accomplished by creating a signing (OpenPGP) key.
But why, you may ask, do you have to verify your identity. The answer is simple, in order to maintain the integrity of the Maven central ecosystem. By signing your artifact, you are enabling anyone who uses artifacts from maven central to be able to verify that the packages they receive do indeed come from you and have not been modified in any way.
Before going into detail of how to do this, I will summarize the whole signing process here. Basically you create a GnuPG signing keypair containing the private and public keys. The private key is used to sign your artifact, while your public key must be hosted on a public PGP server, allowing anyone to be able to verify your artifacts.
In order to generate a new keypair, you need to enter the following command in your terminal (assuming GnuPG is properly installed on your machine):
Follow the instructions at the command prompt and accept the default settings which are recommended. A few things to note:
You can leave the default key without an expiration date. It is possible to change the expiration date after creating the key, but it may be difficult to communicate it.
Choose a good passphrase and guard it carefully. If someone were to have access to your key, (bad things could happen)™.
There are several GUI front-ends for GnuPG available which you could use to generate the key if you do not want to work on the command line.
Next you need to upload the public part of your generated key to a public PGP server. Uploading can be done with the following command in your terminal:
gpg –keyserver pgp.mit.edu –send-key <keyID>
The Key ID looks something like 5DED768A and is also the name of the key file which is generated
PGP keys are forever. Once you upload a key, you cannot remove it anymore. You may however generate a revocation certificate to let others know that the key is invalid. The MIT PGP public key server FAQ is a good read.
Once you have created and uploaded your key, you should now configure maven to use your key for signing your artifacts. For this, there is the maven-gpg-plugin (note that the gpg command must be available from your terminal when using this plugin).
Ideally we want the artifact to be signed only when we are performing a release, not during development builds. We therefore specify in the POM file that we want signing to be activated only for releases. This is accomplished by adding the following profile to your POM file:
Now you’re all set. When performing a release build, you will be prompted for your passphrase and the artifact will be signed using your GnuPG key.
Having built and signed the artifacts, the next step would be boarding the train to Maven Central.
In a previous post, I mentioned that the Android Contact Picker library is now deployed to maven central. Getting there was a multi-day process which involved a lot of Googling to figure out stuff. Thanks to blogs like this and this, I was able to finally get through the process. But it can be a bit tedious if you are new to all the side-processes involved.
For this reason, I want to document the whole process again for myself and maybe for anyone who might find it useful. I am doing a series about deploying to maven central, starting with preparing your POM file right up to final deployment. The basic assumption here is that you know your way around maven and are looking to deploy to Central.
As there are many ways to get to Maven Central, I am going to focus on using the Sonatype Express which takes only Open Source Software passengers. There is a guide to the Sonatype OSS Maven repository, which focuses on how to deal with things on their end. These series of posts focus on what you the developer need to do to prepare your artifacts for maven central.
This post will focus on the first step, which is preparing your POM file.
Part 1: Verify your luggage – Is your POM ready?
I am assuming you already use maven for building your project (hence the interest in deploying to maven central). This means you know what the pom.xml file is, and if you do not, take a look at the Complete Maven Reference and the POM reference. Maven can easily build your project with a minimum of information like the packaging, dependencies etc.
However, much more is needed in order to deploy your artifacts so that they can be reliably shared with others and dependencies properly resolved. There is a minimum set of tags required in the POM file in order to improve the central repository and support the Maven ecosystem. The minimum required tags are the following:
More details on each of the elements can be found in the POM reference. You can take a look at the Android Contact Picker POM file for an example of how to enter the attributes. Here are a few additional notes about some of the required elements in the POM:
- Choose your Maven coordinates carefully. They need to be unique to your project. Use your domain name or that of your organization as prefix. It is usually recommended, but not required that the coordinates match your Java package names.
- While still in the development phase, use the –SNAPSHOT suffix in your project version. For example <version>2.2.0-SNAPSHOT</version>. This enables you to always get the latest development build when testing.
- Version control links are important (and mandatory) and most popular versioning systems are supported by Maven. They will also be used during the final release phase by the maven-release-plugin.
- Putting the release repository/pluginRepository in your POM is discouraged. In ideal conditions, all your dependencies should be already in central and central repository is self-contained.
Once your pom file has all the necessary components in place you should test your build by running maven clean install. This will build your project and install it into your local maven repository. If this succeeds, then you are ready to go on to the next step. If not, look at the errors and fix any issues and rebuild. Rinse and repeat until it works.
The next stop en route to Maven Central and the topic of the next post is verifying your identity.
Photo credit: Steven Barker on Flickr
The Android Contact picker library is a simple Android library which allows you in one API call to:
- Display list of contacts
- User selects a contact
- Display contact details
- User selects a phone number
- Perform an action with the number
Actually the library has been out for quite a while now, so you may already know/use it. However, since I first wrote the library, I have discovered the maven build tool (which is very awesome, if you configure it right).
Well Android Contact Picker is now available from the Maven Central repository and you can use it simply in your project by including the dependency in your pom file
Last I checked, if you use Eclipse, then you will need to download the project and import it into your workspace in order for Eclipse to be able to resolve the references.
However, if you use IntelliJ (which I now use for the library) then when you include the dependency in your pom file, it will download the project, import it, build and resolve all references related to the project. You can then be on your merry way building that awesome app of yours. Yeah I know, IntelliJ is cool in that regard.
This version is principally the same as the 2.1 version. So if that works for you, you can stick with it. Well, there is one small difference, custom phone number labels are now properly displayed instead of just the text “Custom”.