- 1. Introduction
- 1a. Terms of Service
- 2. Sign up
- 3. Create a JIRA ticket
- 4. Maven Repositories
- 5. Prerequisites
- 6. Central Sync Requirement
- 7a. Deploy Snapshots and Stage Releases with Maven
- 7a.1. POM and settings config
- 7a.2. Publish Snapshots
- 7a.3. Stage a Release
- 7b. Stage Existing Artifacts
- 7c. Deploy Snapshots and Stage Releases with Ant
- 7d. Stage Releases with Gradle
- 7e. Deploy and Stage with SBT
- 8a. Release It
- 8.a.1. Closing a Staging Repository
- 8.a.2. Releasing a Staging Repository
- 8b. Automating Releases
- 8c. Automating Releases in Nexus 2.4
- 9. Activate Central Sync
- 10. Help
- 11. What Do People Think About OSSRH
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.
|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.
You need a Sonatype JIRA account to create tickets and access your Maven repositories. Go to https://issues.sonatype.org/
- Click the Sign Up link under the Username field.
- 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.
- Create a ticket with Project of Support - Open Source Project Repository Hosting and Issue Type of New Project in the OSSRH JIRA.
- 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.
|https://oss.sonatype.org/content/repositories/snapshots/||repository for deploying snapshots|
|https://oss.sonatype.org/service/local/staging/deploy/maven2/||repository for staging releases, you should never visit this url in browser|
|https://oss.sonatype.org/content/repositories/releases/||repository where staging promotion will go, this repository is synced to The Central Repository, but you should not deploy to this repository directly|
|https://oss.sonatype.org/content/groups/public/||repository group which contains snapshots and releases|
- 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.
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.
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.
- 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
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.
Configure your POM to inherit from Sonatype OSS Parent POM:
Configure your POM's SCM element with the information matching your SCM repository like this:
You need to store your HTTP login so hg push won't ask for it from command line.
Edit .hg/hgrc like this:
See the Maven SCM docs for more information.
Configure your Maven settings.xml, typically located in your ~/.m2 directory:
To publish a snapshot, simply run:
If you experience a HTTP 401 error during deployment, make sure your settings.xml is correctly configured and you can log in to https://oss.sonatype.org 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, you will need log in to https://oss.sonatype.org using the same credentials you used to sign up for access to the Sonatype JIRA, 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:
First you need to prepare a release:
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.
You don't have to go through steps 7.a.1. through 7.a.3. if your artifacts have already been released or if you've generated your artifacts using something other than Maven. The steps below allow you to skip using the maven-release-plugin entirely. You can either use the maven-gpg-plugin to sign and deploy your artifacts or upload a staging bundle.
For example, if you want to sign and deploy these artifacts, you will first need to sign them:
You can run mvn javadoc:jar and mvn source:jar respectively to generate -javadoc.jar and -sources.jar.
by Martijn Verburg
Per section 6 above, all project artifacts must be signed using GPG, and your public key must be distributed to hkp://pool.sks-keyservers.net/. For more information, please refer to How To Generate PGP Signatures With Maven. To sign your artifacts using the maven-gpg-plugin, run commands like this:
Because you are specifying -DrepositoryId, make sure you configure a matching server element in settings.xml like this:
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 https://oss.sonatype.org, 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, a staging repository will be created for the bundle and the bundle will be validated to ensure that it meets the requirements laid out in section 6 above. If successful, you will get an e-mail telling you if your artifacts are successfully staged and verified.
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 in Central 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:
Some explanation to the code above:
- xmlns:artifact="antlib:org.apache.maven.artifact.ant" is mandatory for installing Maven Ant Tasks
- you need to package a main jar artifact, a javadoc jar artifact and a sources jar artifact
- the deploy task uses Maven to deploy your main artifacts to the snapshot repository
- the stage task uses Maven to sign and deploy artifacts, you also need to make sure GPG is correctly installed
- maven-snapshots-repository-url is the snapshot deploy URL, maven-snapshots-repository-id is used to identify it
- 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:
- 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.
- 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.
Yennick Trevels wrote an excellent article for Gradle users.
Here are some references to publishing to OSSRH with Scala Build Tool:
NEW https://github.com/xerial/sbt-sonatype – Taro L. Saito (firstname.lastname@example.org) created this sbt-sonatype plugin for publishing Scala projects to Maven central through the REST API of Nexus 2.4. Several projects in GitHub have started to use sbt-sonatype to sync with Maven central.
To release your artifacts, open your favorite browser and go to https://oss.sonatype.org/.
You can deploy artifacts to a same open staging repository multiple times before closing it.
To close a staging repository:
- Login to the Nexus UI at https://oss.sonatype.org.
- Go to Staging Repositories page.
- Select a staging repository. The staging repository name should look like your groupId without punctuation followed by a number (orgmygroupid-1000). If you just finished performing your release, it may take a minute or two for the staging repository to appear on the Staging Repositories page. Also, if there is a long listing of staging repositories with names like central_bundles-*, make sure that you scroll through the listing to find one that bears a name resembling your groupId.
- 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:
- Staging rules fail to pass when you try to close a staging repository, so you have to drop it.
- 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.
Once your artifacts are released, they will be synced to The Central Repository and you will not be allowed to update or delete them.
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.
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
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.
We have created two mailing lists for OSSRH Users:
| List Address
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).
- 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