Thousands of OSSRH users have received a mail to migrate to the new Maven Central Portal. This was referring to https://central.sonatype.org/faq/what-is-different-between-central-portal-and-legacy-ossrh/ promising instructions for the migration.

However, I started the migration and then was totally blocked and left in the rain. As I contacted [email protected] several times but got no answer, I kept digging and decided to create this page to share my experience and collected knowledge with others affected by this delicate situation.

First of all you need to understand that legacy OSSRH and Central Portal are two very different things that are kind of incompatible. Further, once you triggered the migration there is no way back. So before starting such migration carefully read and understand the entire context or you might end up blocking your OSS project being unable to build and deploy.

The two repository and sync services differ significantly:

• Both services use different URLs to login: central.sonatype.com vs. https://s01.oss.sonatype.org/ (or even without s01 for more legacy).

• Both services use different incompatible access token systems.

• Therefore you need to go to https://central.sonatype.com/account and click on Generate User Token.

  • ATTENTION: The new mechanism is far from intuitive.

  • You only have a few seconds to copy your credentials so have your password store ready before clicking the button and hurry up.

  • It seems that only one user token is supported so when you generate a new one, the old one is automatically invalidated what caused me a lot of confusion and trial & error since nothing is documented or explained about this.

• You need to use different maven plugins for deployment: central-publishing-maven-plugin vs. nexus-staging-maven-plugin

• For Gradle it seems there is no real solution available yet so if you are using Gradle better do not hurry to progress with the migration.

• The new plugin automatically derives repository URLs and is not using <distributionManagement>.

• The documentation only states implicitly that the <id> for the <server> credentials is hardwired to central now. As I missed this, I had to learn it from stacktraces with mvn -X.

• In case you are deploying SNAPSHOT releases and maybe even consuming them as artifacts downloaded by maven in modularized builds, there are big changes ahead. For documentation see publishing SNAPSHOTs. So first you need to enable SNAPSHOT deployment for your namespace as described in the documentation.

• However, I am still unable to deploy SNAPSHOTs and always get 403.

• Even if I would be able to deploy them, I am still clueless how I could configure a repository in my pom.xml so that maven can download such SNAPSHOT releases from other modules as my entire project is split into many micro-modules that all have their own git repository and exchange SNAPSHOT releases for CI.

1. Prepare your credentials

   1. Open https://central.sonatype.com/publishing/namespaces

   2. Ensure you can login with your existing OSSRH account

   3. Check that your namespaces are listed properly

   4. See if you have a Migrate Namespace button next to your namespace(s)

   5. Click on that button to check if the automatic migration is possible.

   6. DO NOT START THE MIGRATION YET!!!

   7. Got to https://central.sonatype.com/account

   8. Click on Generate User Token

   9. Quickly copy username and password to your password safe (e.g. KeePass)

   10. Add your new user token to your settings to be able to test local deployments

   11. So edit your settings.xml and add a <server> section with <id>central</id> as described here. Be careful in case you already have (other) credentials with that id and consider using a profile to switch between legacy and new approach.

   12. Ideally use password encryption what is perfectly simplified with IDEasy.

2. Modify and test your project locally

   1. Find your nexus-staging-maven-plugin and remove it or move it to a profile that is not active by default anymore.

   2. Add central-publishing-maven-plugin to be active by default (if you want to switch easily back to legacy then also use a profile).

   3. Test your changes by running a deployment. Since your namespace is not yet migrated, this will fail but you should easily see if there are syntax errors in your pom.xml or the new plugin is not triggered or credentials are not found.

   4. If you have a complex or critical project, I would recommend to create a new test namespace and locally test (SNAPSHOT) deployments via that namespace to ensure all credentials and configs are working well. Also this helps to test your workflows and setup. Simply change the groupId in your pom.xml locally and temporary to the test namespace for your experiments.

3. Finally do the migration when you think you are ready

   1. Click on Migrate Namespace on your namespaces page.

   2. This may take a while, be patient.

   3. If you need SNAPSHOT deployments do not forget to immediately activate this in the context menu next to the namespace and watch the badge to verify the success.

   4. Go to github and edit your secrets for the deployment username and password from the new user token generated above.

   5. Run your regular process to deploy a new release and verify that all works fine. As always be patient since releases need so time from the deployment until they actually arrive on maven central.

This migration is not easy and free of risks. I ran into many pitfalls and blocked my project entirely from any further progress for a significant time what is quite a pain (see issue mmm#2). Therefore, be wise and learn from my mistakes! I hope you find my guide helpful - since I was quite lost with the official documentation I wanted to share this with others so they can avoid similar pain.

My problems are not yet resolved and I have not yet received any feedback from [email protected] but I will update this page, whenever I make progress or get new insights.

Finally, I want to outline that I am very thankful for the services Sonatype is providing for decades. The are actively supporting the Java and Maven community and operate a critical infrastructure with support for thousands of OSS projects for free. Already the resources to provide these Maven terra-bytes of downloads are massive and the service is excellent and available 7x24! Therefore, this is absolutely not an accusation or rant about the migration. I just want to help with the problems I was running into. If this page helps to improve the official documentation, I am happy to delete it as soon as it is not needed anymore.