1. Introduction

Sonatype OSSRH (OSS Repository Hosting Service) uses Nexus to provide Maven repository hosting service for open source projects: https://oss.sonatype.org/. You can deploy snapshots, stage releases, and promote your releases so they will be synced to The Central Repository. All you need to do is to sign up a Sonatype JIRA account, create a JIRA ticket and make some POM/settings configuration. This document will guide you step by step for the details.

1a. Terms of Service

For projects not open sourced If your project is not open sourced, but the license permits free distribution, you can still use OSSRH. Please clarify this when you create JIRA ticket.

2. Sign up

You need a Sonatype JIRA account to create tickets and access your Maven repositories. Go to https://issues.sonatype.org/

1. Click the Sign Up link under the Username field.
2. Fill in the Sign up form and submit.

Don't omit lastname Due to a bug of JIRA and Crowd integration, you have to provide both first name and last name in the 'Full Name' field, eg, 'Juven Xu' is ok but 'Juven' will cause an exception.

3. Create a JIRA ticket

1. Go to Sonatype Open Source Project Repository Hosting JIRA
2. Create a ticket with Project of Support - Open Source Project Repository Hosting and Issue Type of New Project
3. Fill the page with the following information

   Summary	a brief introduction of your project
   groupId	IMPORTANT the groupId of your projects, generally it must match your domain name, so com.googlecode.myprj is valid but myprj is not, if you are unsure about this, please read Choosing your Coordinates
   Project URL	location of the project website
   SCM URL	location of source control system
   Nexus Username	the JIRA Username you just signed up, one or more
   Already Sync To Central	are there any artifacts with same groupId existing in The Central Repository already?
   Description	any other information you think we need to know

After the ticket is created, we will prepare Maven repositories for you. We will update the ticket and set it as _resolved_ once it’s done. Normally it takes less than 2 business days.

How does a new user ask for publish rights to existing repositories Follow step 2, sign up and then leave a comment on the JIRA ticket with the username. We will assign related roles to him and update the ticket.

4. Maven Repositories

5. Prerequisites

• JDK 5+ is installed on your command line path.
• Subversion 1.5+ is installed on your command line path. For more information, please refer to http://subversion.apache.org/.
• Maven 2.2.1+ is installed on your command line path.

  Note Maven 2.1.0 and 2.2.0 produce incorrect GPG signatures and checksums respectively.

• A GPG client is installed on your command line path. For more information, please refer to http://www.gnupg.org/.
• You have created your GPG keys and distributed your public key to hkp://pool.sks-keyservers.net/. For more information, please refer to How To Generate PGP Signatures With Maven.

6. Central Sync Requirement

To Improve The Central Repository and the Supporting the Maven Ecosystem, all artifacts to be synced to central must meet these requirements.

• Project POM has the following elements.
  • <modelVersion>
  • <groupId>
  • <artifactId>
  • <version>
  • <packaging>
  • <name>
  • <description>
  • <url>
  • <licenses>
  • <scm><url>
  • <scm><connection>
  • <developers>
• If the project packaging is jar, and the jar file contains java classes, there must be a -javadoc.jar for main artifact.
• If the project packaging is jar, and the jar file contains java classes, there must be a -sources.jar for main artifact.
• All project artifacts are signed using GPG, and the public key is distributed to hkp://pool.sks-keyservers.net/. For more information, please refer to How To Generate PGP Signatures With Maven.

Sources and Javadoc If, for some reason (for example, license issue or it's a Scala project), you can not provide -sources.jar or -javadoc.jar, please make fake -sources.jar or -javadoc.jar with simple README inside to pass the checking. We don't want to disable the rules because some people tend to skip it if they have an option.

Some folks have asked why do we require all this information in the POM for deployed artifacts so here's a small explanation. The POM being deployed with the artifact is part of the process to make transitive dependencies a reality in Maven. The logic for getting transitive dependencies working is really not that hard, the problem is getting the data. The other applications that are made possible by having all the POMs available for artifacts are vast, so by placing them into the repository as part of the process we open up the doors to new ideas that involve unified access to projects.

We also ask for license now because it is possible that your project's license may change in the course of its life time and we are trying create tools to help normal people sort out licensing issues. For example, knowing all the licenses for a particular graph of artifacts we could have some strategies that would identify potential licensing problems.

Besides, we discourage putting release repository/pluginRepository in your POM. In ideal conditions, all your dependencies should be already in central and central repository is self-contained. Otherwise people's build might break because of missing dependencies. If some of your dependencies are not in central, please upload them using our 3rd-party artifacts bundle upload service.

Brian has written 2 posts from different angles:

• Why Putting Repositories in your POMs is a Bad Idea
• Why external repos are being phased out of Central

 <project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.apache.maven</groupId>
  <artifactId>maven</artifactId>
  <packaging>jar</packaging>
  <name>Maven core</name>
  <version>2.0</version>
  <description>The maven main core project description</description>
  <url>http://maven.apache.org</url>
  <licenses>
    <license>
      <name>The Apache Software License, Version 2.0</name>
      <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
      <distribution>repo</distribution>
    </license>
  </licenses>
  <scm>
    <url>http://svn.apache.org/viewcvs.cgi/maven</url>
    <connection>http://svn.apache.org/viewcvs.cgi/maven</connection>
  </scm>
  <developers>
    <developer>
      <id>...</id>
      <name>...</name>
      <email>...</email>
    </developer>
  </developers>
  <dependencies>
    <dependency>
      <groupId>...</groupId>
      <artifactId>...</artifactId>
      <version>...</version>
    </dependency>
    ...
  </dependencies>
  <!--
  AVOID RELEASE REPOSITORY/PLUGINREPOSITORY:
  <repositories></repositories>
  <pluginRepositories></pluginRepositories>
  -->
</project>

7a. Deploy Snapshots and Stage Releases with Maven

Note When deploying artifacts using Maven or any of the other methods below, there is currently a limit of roughly 200MB on any single file uploaded to OSSRH. Your uploads will fail with a broken pipe exception when you hit this limit.

7a.1. POM and settings config

Configure your POM to inherit from Sonatype OSS Parent POM:

<project>
  ...
  <parent>
    <groupId>org.sonatype.oss</groupId>
    <artifactId>oss-parent</artifactId>
    <version>7</version>
  </parent>
  ...
</project>

Configure your POM's SCM element with the information matching your SCM repository like this:

<project>
  ...
  <scm>
    <connection>scm:svn:http://foo.googlecode.com/svn/trunk/</connection>
    <developerConnection>scm:svn:https://foo.googlecode.com/svn/trunk/</developerConnection>
    <url>http://foo.googlecode.com/svn/trunk/</url>
  </scm>
  ...
</project>

Note If you don't use the standard svn layout , you must configure tagBase of maven-release-plugin.

or

<project>
  ...
  <scm>
    <connection>scm:git:git@github.com:juven/git-demo.git</connection>
    <developerConnection>scm:git:git@github.com:juven/git-demo.git</developerConnection>
    <url>git@github.com:juven/git-demo.git</url>
  </scm>
  ...
</project>

or

<project>
  ...
  <scm>
    <connection>scm:git:https://code.google.com/p/foo/</connection>
    <developerConnection>scm:git:https://code.google.com/p/foo/</developerConnection>
    <url>http://code.google.com/p/foo/source/browse</url>
  </scm>
  ...
</project>

or

<project>
  ...
  <scm>
    <connection>scm:hg:http://bitbucket.org/juven/hg-demo</connection>
    <developerConnection>scm:hg:https://bitbucket.org/juven/hg-demo</developerConnection>
    <url>http://bitbucket.org/juven/hg-demo</url>
  </scm>
  ...
</project>

Note You need to store your HTTP login so hg push won't ask for it from command line. Edit .hg/hgrc like this: [auth] hg-demo.prefix = https://bitbucket.org/juven/ hg-demo.username = juven hg-demo.password = ******

Information See the Maven SCM docs for more information.

Configure your Maven settings.xml, typically located in your ~/.m2 directory:

<settings>
  ...
  <servers>
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your-jira-id</username>
      <password>your-jira-pwd</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your-jira-id</username>
      <password>your-jira-pwd</password>
    </server>
  </servers>
  ...
</settings>

7a.2. Publish Snapshots

Information Have no idea what a SNAPSHOT version is? The POM Syntax section of the book Maven: The Complete Reference is for you. We highly recommend this book if you are new to Maven. SNAPSHOT versions are NOT synchronized to Central. If you wish your users to consume your SNAPSHOT versions, they would need to add the snapshot repository to their Nexus, settings.xml, or pom.xml Successfully deployed SNAPSHOT versions will be found in https://oss.sonatype.org/content/repositories/snapshots/

To publish a snapshot, simply run:

Note If you experience a HTTP 401 error during deployment, make sure your settings.xml is correctly configured and you can log into Nexus UI using the server username/password. See this blog for more details in troubleshooting 401 errors during deployment.

Don't worry about deploying too many snapshots so server disk will be overloaded. Nexus server has a scheduled task running weekly for cleaning up old snapshots. Snapshots older than 15 days will be deleted while a 5 minimum will always be kept. If a version is released, then all snapshots of this version will be removed.

If you want to selectively delete some snapshots, log into Nexus UI, go to the Repositories page and browse the Snapshots repository. In the repository tree view, right click on the node you want to delete and select Delete, just like this:

7a.3. Stage a Release

First you need to prepare a release:

Note Preparing the release will create the new tag in SVN, automatically checking in on your behalf.

Then stage the release:

Maven will checkout the tag you just prepared, then build and deploy it into Nexus staging repository.

7b. Stage Existing Artifacts

You don't have to go though the maven-release-plugin steps if your artifacts are already released. maven-gpg-plugin can help sign and deploy artifacts.

For example, if you want to sign and deploy these artifacts:

Tip You can run mvn javadoc:jar and mvn source:jar respectively to generate -javadoc.jar and -sources.jar. by Martijn Verburg

Run commands like this:

Note that when you sign and deploy classifiers like sources and javadoc, you need to specify the -Dclassifier parameter.
Besides, -DrepositoryId means you need to configure a matching server element in settings.xml like this:

<settings>
  ...
  <servers>
    ...
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your-jira-id</username>
      <password>your-jira-pwd</password>
    </server>
  </servers>
  ...
</settings>

The other way to stage existing artifacts is to create a bundle and upload it. For example, if you have the following artifacts:

First create a bundle with a command like this:

Then go to Nexus UI, click Staging Upload in the left column. In the Staging Upload panel, select Artifact Bundle as Upload Mode and select the bundle you just created, like this:

Now click the Upload Bundle button, staging repository will be created and Nexus will run rules on it. You will get a report telling you if your artifacts are successfully staged and verified.

7c. Deploy Snapshots and Stage Releases with Ant

Maven repositories (even The Central Repository) are not limited to Maven users, Ant users can deploy artifacts to Maven repositories as well. First you need to manually create a pom.xml, which must contain all the elements specified inCentral Sync Requirements.

Now your project directory should look like this:

Then install the Maven Ant Tasks. Download it from http://maven.apache.org/ant-tasks/download.html and put it into ~/.ant/lib/.

Now write your Ant build.xml like this:

<project name="ant-demo" default="deploy" basedir="." xmlns:artifact="antlib:org.apache.maven.artifact.ant">

	<property name="src" location="src" />
	<property name="build" location="build" />
	<property name="dist" location="dist" />

	<!-- define Maven coordinates -->
	<property name="groupId" value="com.juvenxu" />
	<property name="artifactId" value="ant-demo" />
	<property name="version" value="1.0-SNAPSHOT" />

        <!-- define artifacts' name, which follows the convention of Maven -->
	<property name="maven-jar" value="${dist}/lib/${artifactId}-${version}.jar" />
	<property name="maven-javadoc-jar" value="${dist}/lib/${artifactId}-${version}-javadoc.jar" />
	<property name="maven-sources-jar" value="${dist}/lib/${artifactId}-${version}-sources.jar" />

        <!-- defined maven snapshots and staging repository id and url -->
	<property name="maven-snapshots-repository-id" value="sonatype-nexus-snapshots" />
	<property name="maven-snapshots-repository-url" value="https://oss.sonatype.org/content/repositories/snapshots/" />
	<property name="maven-staging-repository-id" value="sonatype-nexus-staging" />
	<property name="maven-staging-repository-url" value="https://oss.sonatype.org/service/local/staging/deploy/maven2/" />


	<target name="init">
		<mkdir dir="${build}" />
		<mkdir dir="${dist}/lib" />
	</target>

	<target name="compile" depends="init" description="compile the source ">
		<javac srcdir="${src}" destdir="${build}" />

	</target>

	<target name="dist" depends="compile" description="generate the distribution">

		<!-- build the main artifact -->
		<jar jarfile="${maven-jar}" basedir="${build}" />

		<!-- build the javadoc artifact -->
		<javadoc sourcepath="${src}" destdir="${dist}/javadoc" />
		<jar jarfile="${maven-javadoc-jar}">
			<fileset dir="${dist}/javadoc" />
		</jar>

		<!-- build the sources artifact -->
		<jar jarfile="${maven-sources-jar}">
			<fileset dir="${src}" />
		</jar>
	</target>

        <target name="deploy" depends="dist" description="deploy snapshot version to Maven snapshot repository">
		<artifact:mvn>
			<arg value="org.apache.maven.plugins:maven-deploy-plugin:2.6:deploy-file" />
			<arg value="-Durl=${maven-snapshots-repository-url}" />
			<arg value="-DrepositoryId=${maven-snapshots-repository-id}" />
			<arg value="-DpomFile=pom.xml" />
			<arg value="-Dfile=${maven-jar}" />
		</artifact:mvn>
        </target>

        <!-- before this, update project version (both build.xml and pom.xml) from SNAPSHOT to RELEASE -->
	<target name="stage" depends="dist" description="deploy release version to Maven staging repository">
		<!-- sign and deploy the main artifact -->
		<artifact:mvn>
			<arg value="org.apache.maven.plugins:maven-gpg-plugin:1.3:sign-and-deploy-file" />
			<arg value="-Durl=${maven-staging-repository-url}" />
			<arg value="-DrepositoryId=${maven-staging-repository-id}" />
			<arg value="-DpomFile=pom.xml" />
			<arg value="-Dfile=${maven-jar}" />
                        <arg value="-Pgpg" />
		</artifact:mvn>

		<!-- sign and deploy the sources artifact -->
		<artifact:mvn>
			<arg value="org.apache.maven.plugins:maven-gpg-plugin:1.3:sign-and-deploy-file" />
			<arg value="-Durl=${maven-staging-repository-url}" />
			<arg value="-DrepositoryId=${maven-staging-repository-id}" />
			<arg value="-DpomFile=pom.xml" />
			<arg value="-Dfile=${maven-sources-jar}" />
			<arg value="-Dclassifier=sources" />
                        <arg value="-Pgpg" />
		</artifact:mvn>

		<!-- sign and deploy the javadoc artifact -->
		<artifact:mvn>
			<arg value="org.apache.maven.plugins:maven-gpg-plugin:1.3:sign-and-deploy-file" />
			<arg value="-Durl=${maven-staging-repository-url}" />
			<arg value="-DrepositoryId=${maven-staging-repository-id}" />
			<arg value="-DpomFile=pom.xml" />
			<arg value="-Dfile=${maven-javadoc-jar}" />
			<arg value="-Dclassifier=javadoc" />
                        <arg value="-Pgpg" />
		</artifact:mvn>
	</target>

	<target name="clean" description="clean up">
		<delete dir="${build}" />
		<delete dir="${dist}" />
	</target>

</project>

Some explanation to the code above:

1. xmlns:artifact="antlib:org.apache.maven.artifact.ant" is mandatory for installing Maven Ant Tasks
2. you need to package a main jar artifact, a javadoc jar artifact and a sources jar artifact
3. the deploy task uses Maven to deploy your main artifacts to the snapshot repository
4. the stage task uses Maven to sign and deploy artifacts, you also need to make sure GPG is correctly installed
5. maven-snapshots-repository-url is the snapshot deploy URL, maven-snapshots-repository-id is used to identify it
6. maven-staging-repository-url is the staging deploy URL, maven-staging-repository-id is used to identify it

To make the Ant script work, you also need to create a XML at ~/.m2/settings.xml, with content like this:

<settings>
  <servers>
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
  </servers>
  <profiles>
    <profile>
      <id>gpg</id>
      <properties>
        <gpg.passphrase>xxxxxx</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
</settings>

1. the <server> element is used to configure nexus access credential, its id must be identical to the value of maven-snapshots-repository-id and maven-staging-repository-id property in build.xml.
2. the <profile> element is used to provide your gpg passphrase, it's not a good idea to put it directly into build.xml, so you should put passphrase here, and <arg value="-Pgpg" /> in build.xml will make it work.

To deploy a SNAPSHOT, make sure the 'version' element in your pom.xml the 'version' property in your build.xml has a SNAPSHOT version value (like 1.0-SNAPSHOT), then run ant deploy.
To stage a release, make sure the 'version' element in your pom.xml the 'version' property in your build.xml has a RELEASE version value (like 1.0), then run ant stage.

7d. Stage Releases with Gradle

Yennick Trevels wrote an excellent article for Gradle users.

7e. Deploy and Stage with SBT

Here are some references to publishing to OSSRH with Scala Build Tool:

http://www.cakesolutions.net/teamblogs/2012/01/28/publishing-sbt-projects-to-nexus/

https://github.com/sbt/sbt.github.com/blob/gen-master/src/jekyll/using_sonatype.md

https://raw.github.com/paulp/scala-improving/master/project/PublishToSonatype.scala

8a. Release It

To release your artifacts, open your favorite browser and go to Nexus UI with address: https://oss.sonatype.org/.

Note You can deploy artifacts to a same open staging repository multiple times before closing it.

To close a staging repository:

1. Login to the Nexus UI.
2. Go to Staging Repositories page.
3. Select a staging repository.
4. Click the Close button.

You will be asked to provide a description for this staging close operation. If the staging repository is closed successfully, you will get a notification email and confirmation via the ui.

See the image below for details.

To make sure the deployed artifacts meet the Central Sync Requirements , Nexus has a few staging rules running on Staging Close and Release. These rules will validate your deployment has correct POM, javadoc, source, pgp signatures, and checksums etc. If your deployment has any problem, you will get a report like this:

Then you have to find out what's causing the problem, drop the staging repository, fix your release, and deploy again.

After staging repository is closed successfully, you can click on it to get a repository tree view. You will want to download them and do some manual testing  (or hold a community vote) before finally releasing them. To download an artifact, right click on it and select Download.

In these 2 cases you will want to drop a staging/staged repository:

1. Staging rules fail to pass when you try to close a staging repository, so you have to drop it.
2. Staging repository is closed, but when you test the artifacts in the staged repository, you find some problems. So you will want to drop it and stage again.

To drop a staging repository, select it and click the Drop button, see the image below.

When you are sure the closed staging repository has no problem, click the Release button. You will be asked to input a description for this release. Staging rules will run again. If the closed staging repository is released successfully, you will get a notification email. Now your artifacts are in the Releases repository, which is synced to The Central Repository roughly every 2 hours. Now you can browse or search your artifacts from Nexus UI.

Note Once your artifacts are released, they will be synced to The Central Repository and you will not be allowed to update or delete them.

8b. Automating Releases

You are not limited to using the Nexus Web UI to close/release your Staging repositories. If you want to automate the Staging process, you can use the Nexus Staging Maven Plugin or Ant Tasks. Please read Build Promotion with the Nexus Staging Suite in the book Repository Management with Nexus for more information.

8c. Automating Releases in Nexus 2.4

Note Please consult this section of Repository Management with Nexus for instructions on using the nexus-staging-maven-plugin with Nexus 2.4. The links below will take you to detailed documentation on the plugins themselves.

Once OSSRH is upgraded to version 2.4 of Nexus, users who have been automating the close and/or release of staging repositories may need to modify their build procedures in the following scenarios:

• Users who use the nexus-maven-plugin will have to use nexus-staging-maven-plugin version 1.4.4
• Users who already use the nexus-staging-maven-plugin will have to upgrade to version 1.4.4. This should be as simple as changing the version element for the plugin in your POM.
• Users who use nexus-ant tasks will have to upgrade to version 1.4
• Users who are calling the REST API directly to close/release staging repositories you will need to consult the Nexus 2.4 API documentation to determine what changes they may need to make. The new API calls will be available here after the upgrade is complete: https://oss.sonatype.org/nexus-staging-plugin/default/docs/index.html

9. Activate Central Sync

The first time you promote a release, you need to comment on the OSSRH JIRA ticket you created in Section 3 so we can know you are ready to be synced. We will review your promoted artifacts. If no problem found, we will activate Central Sync for you and close your JIRA ticket.

After Central Sync is activated, your future promotion will be synced automatically. The sync process runs roughly every 2 hours.

10. Help

We have created two mailing lists for OSSRH Users:

Upon account creation, you will automatically be added to the Announcements List. This list will be used for outbound announcements regarding system upgrades and other changes that affect your projects. All replies to this list are redirected back to the user list which is where more general discussion in the community will take place.

You can also come to our IRC (irc.codehaus.org, channel #mavencentral).

11. What Do People Think About OSSRH

• Automated Gradle project deployment to Sonatype OSS Repository by Yennick Trevels on Nov 5, 2011
• Want to host on Maven Central? by Kvahuja on Sep 8, 2011
• Deployer un artefact sur repo1.maven.org [French] by Issam El Fatmi and Cyrille Le Clerc on Jul 22, 2011
• How to upload your artifacts to maven central by umut.utkan on Apr 24, 2011
• Releasing Maven Artifacts to Central Repository through Sonatype by Jarrod Roberson on Mar 22, 2011
• Automating publishing to maven central via Sonatype by Yan Pujante on Nov 27, 2010
• Publishing javassist releases to Sonatype public repo/maven central by Andrew Dinn on Jul 27, 2010
• Automating Releases with maven-release-plugin [covered a lot on CVS and PGP] by Michael Remijan on May 20, 2010
• Free Maven Repository Hosting for Open Source projects by Sonatype by James Lorenzen on Mar 1, 2010
• Sonatype Free Maven Repository Hosting For FLOSS projects - Great Stuff! by Fabrizio Giudici on Feb 26, 2010
• Releasing a project to Maven Central repository via Sonatype by Jakub Holý on Feb 7, 2010