Publishing (Early Access)

Introduction

Alert

If you currently publish to oss.sonatype.org or s01.oss.sonatype.org, please continue to use our original publishers' guide. If you are interested in Publisher Early Access, please send a message to central-support@sonatype.com, so we can walk you through the migration process.

Publisher Early Access enables you to do the following on https://central.sonatype.com:

• Claim a publishing namespace
• Publish components to Maven Central using a web interface
• Publish components to Maven Central using a Maven build plugin
• Set up a webhook for notifying you when your components have been successfully published
• Manage your credentials

If you are not currently publishing artifacts to Maven Central on an oss.sonatype.org host, and if you are comfortable with manually publishing components on https://central.sonatype.com, then keep reading for a step-by-step guide that takes you through the entire process from signup to uploading your first components!

Prerequisites

While Publisher Early Access is not meant to replace the existing workflow, there are several notes worth repeating from our original publishing guide.

Any components you successfully publish with Publisher Early Access will sync with Maven Central

As such, you are bound by and should review our full terms of service.

Once released/published, you will not be able to remove/update/modify your components.

Please see the Can I change (modify, delete, update) a component on Central? FAQ for more details on this long-standing policy.

Sign Up or Sign In

If you haven't signed up for Publisher Early Access or have been automatically signed out, click the "Sign In" link at the top right of https://central.sonatype.com:

Publisher Early Access supports social logins via Google or GitHub. You can also choose your own username and password. If you choose to sign up with a social login, Sonatype will receive access to the e-mail address associated with your social login account. Our Identity Provider supports multiple social logins, so, if you would like to see more providers in the future, please let us know!

Important

Please provide a valid e-mail when signing up. You will need access to that e-mail address to complete the signup process. Sonatype will use also use that e-mail address to communicate with you whenever you need support with Publisher Early Access.

Managing Your Credentials

If you've forgotten your password, or simply want to rotate your credentials as part of good password hygiene, you can find a link to reset your password at the bottom of the Sign-In form:

Clicking that link will bring you to the Reset Password form:

Alert

Sonatype will never contact you for your password. You must use the links on https://central.sonatype.com to manage your credentials.

Choosing a Namespace

If you are new to Publisher Early Access, 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..

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. From our original guide:

Similar to the Java package naming convention it reuses 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.

Adding a Namespace

To add a namespace, click on your username/e-mail 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:

You can then click on either button labelled "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:

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

Verifying a Namespace

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.

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

• 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.

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 minutes to complete or returns an error, please send an e-mail to central-support@sonatype.com and provide as much supporting information as you can (e.g. screenshots, logs, steps to reproduce). If you already have an account in our JIRA, you can create a support ticket using this link.

Publishing Your Components

After your namespace has been verified, you're finally ready to start uploading components to Maven Central!

Publishing By Uploading a Bundle

Publisher Early Access supports uploading a zip file containing your components and accompanying required files (metadata, checksums, signatures). Assembling this zip file will depend on your build tooling and process. You can find generic guidance on assembling a zip for upload in our existing guide to manual deployments.

Important

Publisher Early Access currently supports common archive extensions, e.g. zip, jar, tar.gz. While you can only upload one zip at a time per publishing request, the archive can contain more than one component. You can upload an archive up to 1GB in size. If your upload fails with an error or does not result in the creation of a deployment, first check to see if the file is less than 1GB in size and that it extracts properly with a local archive extract tool. If the archive is valid and fits into the size limit but still won't upload, please send an e-mail to central-support@sonatype.com and provide as much supporting information as you can (e.g. screenshots, logs, steps to reproduce). If you already have an account in our JIRA, you can create a support ticket using this link.

If you have at least one verified namespace, you can click the "Publish Component" button from the Namespaces tab:

You can also click the "Publish" link in the top right or on the "Deployments" tab under "Publishing Settings" to arrive here:

From here, you can click either button labelled "Publish Component":

Enter a "Deployment Name." This will help you identify what you're attempting to publish (e.g. given that you're publishing to Maven Central, you could add your coordinates, i.e. "your.groupId:your.artifactId:0.0.your-version"). You can also provide a longer, optional "Description".

Scroll to the bottom of the popup to find the "Upload File" button:

Click this button to choose a file from your computer, and then click the "Publish Component" button to being the upload.

Publishing By Using the Maven Plugin

Publisher Early Access currently also supports publishing via Maven. In order to do this, you need to configure your project to use the central-publishing-maven-plugin.

Note

The plugin does not attempt to generate all of the prerequisites for a valid bundle, so you'll want to follow the documentation for building Javadoc and sources .jar files and GPG signature files. There are additional metadata requirements (specifically required elements in your POM) that the plugin will not enforce. Have a look at this section of our documentation for guidance on meeting these requirements.

<plugin>
  <groupId>org.sonatype.central</groupId>
  <artifactId>central-publishing-maven-plugin</artifactId>
  <version>0.1.2</version>
  <extensions>true</extensions>
  <configuration>
    <publishingServerId>central</publishingServerId>
    <tokenEnabled>true</tokenEnabled>
  </configuration>
</plugin>

Credentials

As with the prior Maven deployment process, you'll need to configure your settings.xml with your credentials. By default, this will expect your login credentials. You can get these credentials by generating a user token via the Account page and setting tokenEnabled to true in the plugin configuration.

<settings>
  <servers>
    <server>
      <id>central</id>
      <username><!-- your token username --></username>
      <password><!-- your token password --></password>
    </server>
  </servers>
</settings>

Publishing

Once your build is configured, running mvn deploy will generate a bundle and upload it to the Portal for validation. A successful publish will look similar to the following:

$ mvn deploy
...
[INFO] --- central-publishing:0.1.2:publish (injected-central-publishing) @ example_java_project ---
[INFO] Staging 7 files
...
[INFO] Generate checksums for dir: com/sonatype/central/example/example_java_project/0.0.6
[INFO] Going to create /home/central/example_java_project/target/central-publishing/central-bundle.zip by bundling content at /home/central/example_java_project/target/central-staging
[INFO] Created bundle successfully /home/central/example_java_project/target/central-staging/central-bundle.zip
[INFO] Using Central baseUrl: https://central.sonatype.com
[INFO] Using credentials from server id central.staging in settings.xml
[INFO] Using Usertoken auth, with namecode: <token user ID>
[INFO] Going to upload /home/central/example_java_project/target/central-publishing/central-bundle.zip
[INFO] Uploaded bundle successfully, deployment name: com.sonatype.central.example:example_java_project (0.0.6), deploymentId: 7f0251ff-eaa4-467d-8d98-da4cf8dc54b3
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  24.778 s
[INFO] Finished at: 2023-09-19T17:58:04-04:00
[INFO] ------------------------------------------------------------------------

Component Validation

After your upload is accepted, Publisher Early Access will begin the validation process:

The validation process ensures that your components meet all the requirements for Maven Central. Validation should not take more than a few minutes. Click the "Refresh" button to see status of the validation process.

If your components do not meet all the requirements, your Deployment will fail, and the right column of the Deployment card, labelled "Validation Results," will detail which validations failed. Once you address those issues in your local build, you can click the "Publish Component" again to start a new Deployment where you can submit the updated zip file.

Once the validation is complete and if there are no errors, you are able to publish your components. Pressing the "Publish" button will sync automatically to Maven Central. Congratulations!

Important

Once released/published, you will not be able to remove/update/modify your components. Please see the Can I change (modify, delete, update) a component on Central? FAQ for more details on this long-standing policy.

Adding a Webhook

Publisher Early Access enables publishers to specify a webhook, which will fire after components have passed validation and are approved for sync to Maven Central. Publishers can use webhooks to get notified in their messaging systems or to trigger other workflows within their organizations.

To add a webhook, click the "View Webhooks" link in the top-right menu under your username/e-mail address:

Provide the required Webhoook URL and, if required, a username and password for our service to send when calling your webhook. Click Save button to save your changes:

If you have provided a valid URL (and optional credentials), your webhook be called as soon as you attempt to publish a component. The webhook will specify details around the success or failure of the publication attempt.