Skip to content

Publishing By Using the Portal OSSRH Staging API⚓︎

The Portal OSSRH Staging API is a partial reimplementation of the OSSRH / Nexus Repository Manager 2 Staging APIs. The intent of this service is to enable publishers who are using existing plugins to have a smooth migration to the Central Publisher Portal. We hope that over time plugins will adopt the Portal API rather than rely on this service.

Reporting Bugs

Although we have tested as many usecases as we could identify, there are going to be ones we did not anticipate. If you encounter a bug or an unsupported plugin, please contact Central Support. Please include the following information:

  • Plugin you are using and any relevant configuration (including your pom.xml or build.gradle files should be sufficient)
  • The error message you received from the service / any relevant build tool output
  • Any other details that you believe would assist us in diagnosing the issue

Overview⚓︎

This service enables previous OSSRH publishers to bring their existing build plugins to the Central Publisher Portal. It also enables new publishers who wish to use a build tool plugin that does not yet provide compatibility with the Portal API.

We hope that this service provides a minimally disruptive path forward from OSSRH. Please follow the corresponding guide below to configure your plugin for publishing through this compatibility service.

Plugins Tested For Compatibility⚓︎

We have tested this service with the following plugins:

* Requires using the manual endpoints documented below

Additionally, the following plugins and tools have not been tested by us, but have declared compatibility with the OSSRH Staging API Service:

If you have working examples of publishing with other plugins that you would like to have us include in this list, please let us know.

Authentication⚓︎

The OSSRH Staging API is a Central Publisher service. As such, it requires publishers to authenticate their requests with Central Portal User Tokens.

Migrated Namespaces

If you previously published via an OSSRH server, you will need to replace your OSSRH token with a Portal token. Publishing with an OSSRH token will result in 401 responses.

Getting Started For "Maven-API-Like" Plugins⚓︎

Gradle's maven-publish plugin

If you are using Gradle's maven-publish plugin, you must follow this section or your deployments will not be visible in the Central Publisher Portal. If you do not see your deployment at https://central.sonatype.com/publishing, please double-check that you have followed these instructions before reaching out to support.

What we term "Maven-API-like" is any plugin that follows the pattern of Maven's built-in maven-deploy plugin. Specifically, plugins that only make a series of PUT requests to a Maven 2 repository structure. (e.g. publishing com.example:example:0.1.0 to the https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/ repository, there would be a request to PUT https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/com/example/example/0.1.0/example-0.1.0.pom).

These plugins are notable because they do not provide information to the service about when one deployment ends and the next begins. As such, Sonatype Nexus Repository Manager 2 separated deployments by making assumptions like requests coming from two different IPs or from two different user agents were for two different releases. The OSSRH Staging API Service currently only differentiates requests by IP.

Configuring The Repository⚓︎

Replace your existing OSSRH endpoint (https://s01.oss.sonatype.org or https://oss.sonatype.org) with https://ossrh-staging-api.central.sonatype.com. For example, the Gradle built-in maven-publish plugin might be configured as

// ...
    repositories {
        maven {
            name = 'ossrh-staging-api'
            url = "https://ossrh-staging-api.central.sonatype.com/service/local/staging/deploy/maven2/"
        }
    }
// ...

Ensuring Deployment Visibility In The Central Publisher Portal⚓︎

In order to ensure that your deployment is transferred from the OSSRH Staging API compatibility service to the main Central Publisher Portal, you must adjust your process in one of the following ways:

1. Modify Your CI Script⚓︎

After all of the artifacts have been uploaded, your CI process should make a request to POST /manual/upload/defaultRepository/<namespace> where <namespace> is the namespace that you see in https://central.sonatype.com/publishing/namespaces when you log in with the account that was used to generate the token. This must be done from the same IP that was used when uploading the files, so adding it to the end of your CI process is the most likely way for this to work reliably._

2. Make Separate Requests⚓︎

If you do not want to update your CI script, you will need to instead make a request to GET /manual/search/repositories?ip=any&profile_id=<namespace> where <namespace> is the namespace that you see in https://central.sonatype.com/publishing/namespaces when you log in with the account that was used to generate the token. From there, you will get a JSON list of repositories. You will need to make a request to POST /manual/upload/repository/<repository key> or DELETE /manual/drop/repository/<repository key> to send the repository's contents to the Central Publisher Portal or to clean up the files, respectively. Please see the further documentation below for those endpoints for parameters that they accept.

Triaging Issues⚓︎

If your build fails, you will likely have a repository that is in a bad state. You will need to manually drop the repository in order to prevent further deployments from encountering issues if they come from the same IP.

Central Publisher Portal v. OSSRH Staging API

The Central Publisher Portal and the OSSRH Staging API are two different services. Dropping a deployment on one service does not drop the repository on the other.

Getting Started for "Nexus Repository Manager 2 API" Plugins⚓︎

If your plugin makes use of the Nexus Repository Manager 2 Staging API, you likely only need to update your configuration and credentials in order to successfully publish.

Configuring Your Plugin⚓︎

Replace your existing OSSRH endpoint (https://s01.oss.sonatype.org or https://oss.sonatype.org) with https://ossrh-staging-api.central.sonatype.com. For example, the gradle-nexus/publish-plugin project might be configured as

// ...
nexusPublishing {
    repositories {
        sonatype {
            nexusUrl.set(uri("https://ossrh-staging-api.central.sonatype.com/service/local/"))
            snapshotRepositoryUrl.set(uri("https://central.sonatype.com/repository/maven-snapshots/"))
        }
    }
}
// ...

From there, you can run the commands that you previously ran. A repository is uploaded to the Central Publisher Portal once the repository is closed.

Documentation of Manual API Endpoints⚓︎

To authenticate your requests to the Manual API Endpoints, you will need to provide an Authorization header the same way that it is done for the Publisher API. Specifically, it expects a Bearer token that is the base64 encoded string of your token username and token password separated by a :.

The following documentation supplements the OpenAPI documentation which provides an interactive environment for testing queries via a web-client.

POST to /manual/upload/defaultRepository/<namespace>⚓︎

When publishing with the default "Maven-like" API, each request is made with no context as to what came before or after it. When publishing to OSSRH, the Nexus Repository Manager server uses a Repository Target to identify the correct Staging Profile. Once it has a Staging Profile, it ensures that an implicitly created Staging Repository exists and then puts the file in the repository. The API itself does not have the concept of closing and releasing repositories, so publishers need to utilize the Nexus Repository Manager Staging API or they need to log in to the UI and manually resume the process from there.

This API endpoint is intended to facilitate similar functionality. As such, it expects the <namespace> value associated with your deployment (e.g. com.example).

The endpoint has an optional parameter of publishing_type, which can either be user_managed, automatic, or portal_api

  • user_managed (default) will upload the deployment to the Publisher Portal, where it can be released or dropped by logging in to https://central.sonatype.com/publishing.
  • automatic will upload the deployment to the Publisher Portal and attempt to automatically release it to Maven Central if it passes validation.
  • portal_api will only upload the deployment to the Publisher Portal. This approach expects that further requests will be made to the Portal Publisher API to get the status of the deployment. The intention of this is to support larger repositories that do not complete validation during the timeout window of a single request.

POST to /manual/upload/repository/<repository key>⚓︎

When publishing with the Nexus Repository Manager Staging API, there are existing endpoints that manage the process of closing repositories and promoting the release. For technical reasons, the reimplemented APIs only upload to the Publisher Portal on closing the repository.

This API endpoint is intended to provide an additional method of uploading to the Portal, for publishers whose process involves logging in to the UI in order to complete a release. It expects a <repository key> value, which can be obtained via the search endpoint documented below.

The endpoint has an optional parameter of publishing_type, which can either be user_managed, automatic, or portal_api

  • user_managed (default) will upload the deployment to the Publisher Portal, where it can be released or dropped by logging in to https://central.sonatype.com/publishing.
  • automatic will upload the deployment to the Publisher Portal and attempt to automatically release it to Maven Central if it passes validation.
  • portal_api will only upload the deployment to the Publisher Portal. This approach expects that further requests will be made to the Portal Publisher API to get the status of the deployment. The intention of this is to support larger repositories that do not complete validation during the timeout window of a single request.

DELETE to /manual/drop/repository/<repository key>⚓︎

When publishing with the Nexus Repository Manager Staging API, there are existing endpoints that manage the process of dropping repositories.

This API endpoint is intended to provide an additional method of cleaning up a repository that is not intended to be uploaded to the Portal, for publishers whose process involves logging in to the UI in order to perform cleanup actions. It expects a <repository key> value, which can be obtained via the search endpoint documented below.

GET to /manual/search/repositories⚓︎

We have provided a search API endpointIn order to facilitate automation of closing and releasing repositories. The following optional query parameters are supported:

Query Parameter Options
profile_id A plugin-specified profile ID string
state open, closed, released
ip any, client, or a specific IP

profile_id is intended to be used in conjunction with features in build tool plugins that target Staging Profiles by ID instead of querying for them based on groupId. An example of this is the stagingProfileId setting on the gradle-nexus/publish-plugin (example documentation).

ip supports querying from a different IP than the one used to publish the deployment.

  • any returns all repositories related to the credentials passed in the request, regardless of IP
  • client (default) returns all repositories specifically related to the IP of the client that is making the request to the service
  • Use of a specific IP allows for further filtering

The response is formatted as such:

{
  "repositories": [
    {
      "key": "<repository key>",
      "state": "<repository state>",
      "portal_deployment_id": "<Central Publisher Portal Deployment ID>"
    }
  ]
}

where the repository state matches the options above and the repository key can be used in the /manual/upload/repository/<repository key> endpoint. The Portal deployment ID can be used as the input to the Portal API Status endpoint in order to track the progress of the deployment all the way to Maven Central.

Known Limitations⚓︎

This service has been implemented with the intent of providing a smooth path forward for the majority of OSSRH publishers to the Central Publisher Portal. Currently, it does not address every potential way of publishing. We are aware of the following limitations that we intend to address if there is sufficient demand:

  • Staging repositories are per-user. The vast majority of staging deployments to OSSRH are done via a single user account, so publishing to the same repository from multiple users is not supported.
  • Staging repositories created via the "Maven-like" API are isolated by IP. This matches the Nexus Repository Manager behavior.
  • Staging repositories need to be closed or manually uploaded to the Portal in order to view them in https://central.sonatype.com/publishing/deployments. From there, publishers can perform manual testing, publish to Maven Central, and drop deployments. However, deployments cannot be modified at that point. This behavior is similar to closed staging repositories in OSSRH.

If you encounter further limitations or wish to give feedback on your particular publishing methodology, please contact Central Support.