Register a Namespace

Choosing a Namespace

If you are new to the Central Portal, you will have no verified namespaces and will see a prompt to view instructions for verifying namespaces:

Important

If you do not see this pop-up AND you signed up with GitHub, then Sonatype was able to grant you permissions to the namespace associated with your GitHub identity automatically. As part of your GitHub subscription, GitHub provides you with a github.io domain that reflects your username and allows you to publish GitHub Pages under that domain. Because of this, Sonatype can, in most cases, automatically verify and provision publishing access to a namespace that looks like io.github.<your GitHub username>.

If you click the "View Instructions to Verify Namespace" button, your browser will open a new tab showing this documentation.

Before you can publish your components, you must choose a namespace. In the Maven ecosystem, this is also known as a groupId, which is one of the three required coordinates to describe any component published to Maven Central, i.e. groupId, artifactId, version. We've previously written about choosing your coordinates in our original publishing guide.

Namespaces identify your top-level project or your organization uniquely across all other publishers whose components are hosted on Maven Central.

Adding a Namespace

To add a namespace, click on your username/email address in the top right corner of https://central.sonatype.com. This will open a dropdown menu, where you can click the "View Namespaces" link:

For DNS

Similar to the Java package naming convention a namespace can reuse the domain name system in a reversed manner. This means that if you are the owner or maintainer of a domain name, you can use any groupId starting with the reverse domain name and as many subsections as you desire.

E.g., if you control example.com, you can use any groupId starting with com.example e.g. com.example.domain, com.example.testsupport and so on. Other examples are

• www.springframework.org -> org.springframework
• subdomain.example.com -> com.example
• my-domain.com -> com.my-domain

Hint

The groupId should reverse the domain name exactly, even if the domain name contains hyphens or other characters that would result in an invalid Java package name. Hyphens are perfectly acceptable in groupIds, and you would not need to change your Java package name to match it.

For Code Hosting Services with Personal groupId

We support a simple verification process for artifacts whose code is hosted in services listed in the table below. If you use one of these services, a simple verification will be required to prove ownership.

For the user myusername on each service

Service	Example namespace
GitHub	io.github.myusername
GitLab	io.gitlab.myusername
Gitee	io.gitee.myusername
Bitbucket	io.bitbucket.myusername

You can then click on either button labeled "Add Namespace":

Enter the namespace you've chosen based on the guidance in the previous section and click "Submit":

Your namespace request will be created, but it will start in the "Unverified" state:

Clicking the "Verify Namespace" button will ask you to confirm whether you're ready for us to verify your namespace (on how to verify, see Verifying a Namespace):

Do not confirm unless you've added a DNS TXT record

Do not proceed with verification unless you have added and verified your DNS TXT record. Doing so will result in namespace verification delays because the NXDOMAIN response is cached, and you'd have to wait until the cache expires for verification to complete successfully.

Clicking "Confirm" will move your request to the "Verification Pending" state:

Verifying a Namespace

By DNS

Before Sonatype can grant you permissions to publish under your requested namespace, we must validate that you own the web domain reflected by your namespace. You can prove domain ownership by adding a DNS TXT record with a value set to the Verification Key we assigned to your namespace request.

Click the clipboard icon next to the Verification Key to copy the value to your computer's clipboard:

You can then use this value in setting up the DNS TXT record with your DNS registrar or web hosting provider. Please see this FAQ for instructions on setting up DNS TXT records with popular DNS registrars and hosting providers.

If you have set up your DNS TXT record correctly, it should only take a few minutes for us to verify your namespace. You can refresh the Namespace page to see if the verification status has changed to "Verified." If verification takes more than a few hours to complete or returns an error, please email Central Support and provide as much supporting information as you can (e.g. screenshots, logs, steps to reproduce).

By Code Hosting Services

If you want to use a domain linked to a Hosting Service we need you to prove ownership of the account by creating a temporary, public repository with a name having the value set to the Verification Key we assigned to your namespace request.

E.g. if you want to use io.gitlab.myusername you must create the public repository like this gitlab.com/myusername/verification-key.

Click the clipboard icon next to the Verification Key to copy the value to your computer's clipboard:

The same applies for the other Hosting Services, e.g. if you want to use com.gitee.myusername you must create the public repository gitee.com/myusername/verification-key.

At the end of the process when your groupId is registered you can simply delete the empty repository. It is only needed during the validation phase.

Namespace details and actions

The menu in the top right of the namespace verification card allows you to do certain actions:

• View ID - This shows you the Verification Key for your namespace request.
• Cancel Verification - This will cancel the verification process and return the request to the "Unverified" state.
• View History - View the status of each of your verification requests. If it takes longer than a few minutes for us to verify your namespace, you can use the View History link to see if there were any errors related to our validation process and find out how you can get help:
• View Users - This is currently unsupported, but in later releases, the Publisher experience on https://central.sonatype.com will allow users to invite other users to publish under namespaces they have already verified.
• Remove Namespace - If you change your mind about using this namespace, click this link to delete your request.

GitHub Namespaces

As mentioned above, if you sign up with a GitHub account, you will automatically receive a verified namespace in the form io.github.<github username>. The intent of this is to reduce the effort required in order to publish to Maven Central, by offloading part of the verification process (proof of domain ownership) to GitHub.

Currently, we only support the GitHub username that you used to sign up, so io.github.<github organization name> is not available as an automatically registered namespace.

If you log in to your account via GitHub and you do not have an automatically created namespace, please email [Central Support for help.

Existing OSSRH Namespaces

If you attempt to register a namespace and the registration fails, it might be because you or someone else has already registered that domain via the old OSSRH publishing workflow. In order to ensure that we uphold the immutability of components published to Maven Central, we do not allow namespaces to be active for both OSSRH and the new Portal workflow.

As documented below, manually publishing has a slightly different structure for the bundled archive file and publishing via Maven requires a different plugin, so you will need to update your existing build process.

As this is in the Early Access phase, we will support migrating back temporarily to the OSSRH workflow if you encounter an issue that would prevent you from successfully publishing within an acceptable time frame.