How To Release Your Open Source Project to Maven Central

 Once you have created and fine-tuned your current programming project, you usually want to share it with all those developers out there who might have a need for your solution. For Java-based projects, Apache Maven provides a good distribution channel for this. With Maven, you can release your project to Maven Central, which is a global repository for open source Java projects that can also be accessed by build tools other than Maven itself. Since I have not found an easy-to-follow guide on how to do this in the web, I try to document the needed steps in this post.

Step #1: Sign Up at Sonatype

Sonatype is a company that provides all sorts of support and tools for “component lifecycle management” as they call it. Essential for us, they provide the access point to making a project available in the Maven Central Repository. You have to create an account at the following sites (for free, of course!):

Step #2: Create your project in JIRA

Log in to the JIRA system at https://issues.sonatype.org/ with the username and password you chose in step 1 and create an issue of type “New Project”. Most input fields are self-explanatory. In any case, here’s what you have to put into those fields:

  • Project: select “Community Support – Open Source”
  • Issue Type: select “New Project”
  • Summary: name of your project
  • Description: to make things easier on the Sonatype guys, drop a line about what your project is about
  • Attachment: don’t add an attachment
  • Group Id: your desired Maven group id (your namespace). This must be a backwards URL like org.wickedsource (which is the namespace I use for my projects). If you’re not familiar with Maven, read this article on how to choose your Maven coordinates.
  • Project URL: URL to your project homepage. You should have a homepage for your project, even if it is just the frontpage of your github or googlecode repository.
  • SCM URL: URL to your source code management system like github or googlecode
  • Username: your JIRA user name
  • Already Synced to Central: choose “No”
  • Epic Link: leave empty

Some of the fields may probably be left empty and they will still create a repository for you, but it makes it easier if you provide all information. The Sonatype guys will usually respond within a couple hours, but it may take longer – be patient.

Step #3: Create a Key Pair

It is required for any artifacts you release to be signed. The easiest way to do this is by using GNU Privacy Guard (I use the Windows version of GPG). If you don’t have a key pair to be used in signatures yet, follow this article on how to generate a key pair and distributing your public key. You will have to choose a passphrase when generating a key pair. This passphrase will be needed later. If you have more than one key pair, make sure you define one of them as the default key pair in GPG.

Step #4: Create and Sign your Artifacts automatically with Maven

Once you have installed GPG and created a key pair you can use the following maven command to sign all your artifacts automatically:

Calling the javadoc and source plugins is necessary to create javadoc and source JAR files along with your actual JAR artifact. Providing javadoc and sources is a requirement for releasing open source projects to Maven Central. The gpg plugin takes care of signing all those JARs with your previously generated default GPG private key.

Caveat: the gpg Maven plugin has to be coaxed into actually signing your javadoc and source JAR files by adding the following configuration to your pom.xml:

Step #5: Deploy your Artifacts to your Staging Repository

If your request for a new Project in the Sonatype JIRA was successful, you will get an answer something like the following:

Configuration has been prepared, now you can:

please comment on this ticket when you promoted your first release, thanks

This basically means that they have provided a staging repository for you where you can upload your artifacts (automatically or manually). From this staging repository you can then manually trigger a release to Maven Central.

The important information is the URL to the staging repository. Add this URL to your pom.xml like this:

Additionally, create a file called “settings.xml” with the following content:

Username and password should be the ones you chose when creating your account at https://oss.sonatype.org. Since the file settings.xml contains your credentials and thus sensitive data, it should only be kept locally and not be committed into any SCM system! The id (“sonatype” in the example above) is used by Maven to create the connection between your credentials and the repository id in your pom.xml.

Now you can call the following Maven command to create, sign and deploy your artifacts:

At some point during the build, you should see that your artifacts are being uploaded to the Sonatype server. The upload may take some while even if your artifacts are rather small, probably because the upload to the Sonatype server is throttled.

Step #6: Promote your Repository

After the Maven build has finished successfully, log in to https://oss.sonatype.org and click the link “Staging Repositories” in the left-side navigation. In the opening tab, select your repository (you can use the “filter by profile” search box in the top right to find your group id). Click on the “close” button to close your repository. This triggers some validation checks on the files you uploaded. You can see if those validations were successful by clicking on the “Activity”-tab in the bottom part of the screen and selecting the “close” node. If there were any errors, fix the errors and deploy again. A documentation of the validations that will be performed when closing a repository can be found here.

Once all validations were successful, you can now promote the repository by clicking the “release” button. This means that you want the contents you uploaded into this repository to be released to Maven Central. After this has been done you should receive an email with the subject “Nexus: Promotion completed” and you should add a comment to the JIRA issue you created and wait for them to activate the sync to Maven Central. This may again take one or two working days. After this, your project has been successfully released to Maven Central and you can upload and then release repositories at any time without having to wait so long (repositories that have been successfully promoted once before will automatically be synced to Maven Central about every two hours from now on).

To check if your project is finally available at Maven Central, you can simply go to http://search.maven.org and search for your group id.

Caveat: I have noticed that sometimes the signature validation failed when I closed a repository on the Sonatype Nexus Server. After repeating the Maven deploy command from step #5 (sometimes a couple times) the signature was validated successfully. I have not yet found out the reason for this, since the uploaded signature files are valid if checked manually with GPG.

Resources

Much of the above information comes from this article in the Sonatype wiki. In the guide above, I added my own experience with releasing Maven artifacts so it should be easier for first-time users to follow.

About these ads

4 comments

    • Tom

      You are quite welcome :). The fact that I didn’t find a step-by-step guide in one central place is exactly the reason I wrote it down.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s