Introduction

Sonatype helps open source projects to set up maven repositories on http://oss.sonatype.org. By being provided with some necessary information of your open source project, Sonatype will provide you free spaces for deploying your maven artifacts, you can use it as your Maven repositories. Besides, if your release artifacts meets some necessary quality requirement, we can review them and sync them into Maven central .

Sign Up

To use our repository service, first you need to sign up on http://oss.sonatype.org . Open this page and click the Sign Up link in the top right corner. You need to fill some basic information and submit the form. A activation link will be sent to your mail box, click the link to activate your Nexus account.

Create a JIRA ticket

Since we need some necessary information to prepare repositories for you, please create a JIRA ticket at https://issues.sonatype.org/browse/OSSRH, note that you might need to sign up a JIRA account.

Now create a new ticket, make sure the Project is Support - Open Source Project Repository Hosting and the Issue Type is New Project, then fill the page with these information:

  • Summary: a brief introduction of your project
  • groupId: groupId of your artifacts
  • Project URL: location of the project website
  • SCM URL: location of source control system
  • Nexus username: the username you signed up at http://oss.sonatype.org
  • Repository Location: if you have a existing repository, we can move the existing release artifacts into Sonatype repository. Note that they must be qualified for central sync up, see the Central Sync Up Requirements section.
  • Already Synced to Central: if yes, we will copy those artifacts to Sonatype repository, and rebuild a correct maven-metadata.xml.
  • Description: any other information you think we need to know, please write here.

After the ticket is created, we will prepare repositories on http://oss.sonatype.org for you. We will update the ticket once it’s done. Normally it takes less than 2 working days.

Deploy Snapshots

You will be told where to deploy your snapshot artifacts, normally the address is http://oss.sonatype.org/content/repositories/snapshots.

Configure your pom.xml and settings.xml like this:

<!-- in pom.xml -->
    <distributionManagement>
        <snapshotRepository>
            <id>sonatype-nexus-snapshots</id>
            <name>Sonatype Nexus Snapshots</name>
            <url>http://oss.sonatype.org/content/repositories/snapshots</url>
        </snapshotRepository>
    </distributionManagement>

<!-- in settings.xml -->
    <settings>
      <servers>
        <server>
          <id>sonatype-nexus-snapshots</id>
          <username>your-nexus-username</username>
          <password>your-nexus-password</password>
        </server>
      </servers>
    </settings>

Note that you should use your username and password at http://oss.sonatype.org for the <server> settings, and the id of the <server> must be same as the <id> of the <snapshotRepository>.

You can only deploy artifacts under your groupId, otherwise you will get 401 error.

Central Sync Up Requirements

We will sync up your release artifacts into Maven Central repository, so before deploying any released artifacts, you must make sure your artifacts are qualified for Central Sync Up.

Make sure your POM does contain all these elements:

  • modelVersion
  • groupId
  • artifactId
  • version
  • packaging
  • name
  • description
  • url
  • licenses
  • scm/url
  • scm/connection
  • developers

Make sure your POM does not contain repositories or pluginRepositories element. Central repository must be self-contained, so all your dependencies must be available in Central. You need to make sure your project can be built without extra repositories or pluginRepositories.

Make sure all artifacts (including pom, jar, war etc.) are signed using GPG, and your public key is available at pgp.mit.edu. If you are not familiar with GPG, please read this blog: How To Generate PGP Signatures With Maven.

Release Your Project

Once you are sure that your project is qualified for Central Sync Up, you can use Maven Release Plugin to release your project and deploy the artifacts to our staging repository. Here we give a simple example for releasing your artifacts:

<!-- in pom.xml -->
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.sonatype</groupId>
  <artifactId>release-test</artifactId>
  <packaging>jar</packaging>
  <version>1.2-SNAPSHOT</version>
  <name>release-test</name>
  <scm>
    <connection>scm:svn:file:///home/juven/services/subversion/release-test/trunk</connection>
    <developerConnection>scm:svn:file:///home/juven/services/subversion/release-test/trunk</developerConnection>
  </scm>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>2.0-beta-7</version>
        <configuration>
          <tagBase>file:///home/juven/services/subversion/release-test/tags</tagBase>
        </configuration>
      </plugin>
    </plugins>
  </build>
  <distributionManagement>
    <repository>
      <id>sonatype-nexus-staging</id>
      <name>Nexus Release Repository</name>
      <url>http://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
    </repository>
  </distributionManagement>
  <profiles>
    <profile>
      <id>release-sign-artifacts</id>
      <activation>
        <property>
          <name>performRelease</name>
          <value>true</value>
        </property>
      </activation>
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-gpg-plugin</artifactId>
            <version>1.0-alpha-4</version>
            <executions>
              <execution>
                <id>sign-artifacts</id>
                <phase>verify</phase>
                <goals>
                  <goal>sign</goal>
                </goals>
              </execution>
            </executions>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>
</project>

<!-- in settings.xml -->
    <settings>
      <servers>
        <server>
          <id>sonatype-nexus-staging</id>
          <username>your-nexus-username</username>
          <password>your-nexus-password</password>
        </server>
      </servers>
    </settings>

Note that this POM is incomplete, the elements in this POM are only used for demonstrating the releasing process, here are some explanation:

  • The scm section is necessary, maven-release-plugin needs this to do scm operations like committing.
  • In the distributionManagement section,the repository url should be the staging repository.
  • Configuration for maven-release-plugin is required, the tagBase is used to tag a stable version.
  • Artifacts should be signed during the release process, here a profile release-sign-artifacts is created, the profile will be automatically activated when the property performRelease is true. maven-release-plugin will set this property to be true when we run mvn release:perform. This profile contains configuration of maven-gpg-plugin, this plugin can help us sign the artifacts.
  • There is a similar profile in Maven's Super POM, it will help us create sources.jar and javadoc.jar when the property performRelease is set to true.

Now the configurations are ready:

  • Run mvn release:prepare, maven will help us update SNAPSHOT version to a release version, commit the change, tag the release version, then update to a new SNAPSHOT version, commit it.
  • Run mvn release:perform, maven will help us checkout the release tag, build it, generate sources.jar and javadoc.jar, sign them, and deploy all of them to the staging repository.

Promote Staged Artifacts

After you released all your modules into the staging repository, you can test them and then choose to drop them or promote them into your release repository.

Log into http://oss.sonatype.org/ UI, click Staging in the left column, then select your staging profile on the right. You will see a open staging repository below, right click on it and select Close. If your artifacts are not qualified for Central Sync, you should be able to see a warning report.

Now you can download artifacts from the staged repository and test them. If problems are discovered, you can right click on the staged repository and select Drop. If you are confident they are ready to be synced to Central, right click on the staged repository and select Promote. Our comment on your JIRA ticket should have told you where to promote artifacts, normally it’s Releases.

Once it’s done, update the JIRA ticket to tell us that you are ready for Central Sync Up. We will review your artifacts and activate the Sync Up.

After activating Central Sync Up, we will close the JIRA ticket. Your artifacts will be synced every hour, this means future artifacts you promote to your release repository will be synced automatically.

Mailing Lists & IRC

We have created two mailing lists for OSSRH Users:

List Address
Unsubscribe
Subscribe
ossrh-announcements@sonatype.org ossrh-announcements-unsubscribe@sonatype.org ossrh-announcements-subscribe@sonatype.org
ossrh-users@sonatype.org
ossrh-users-unsubscribe@sonatype.org ossrh-users-subscribe@sonatype.org

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 #nexus), ping juven.

Twitter is also available: juvenxu .

References

[1] Guide to uploading artifacts to the Central Repository

[2] How to Generate PGP Signatures with Maven

[3] Nexus Staging Suite

[4] Repository Management with Nexus