Publishing By Using the Portal OSSRH Staging API

Migration Required

If you are currently publishing via OSSRH, you will have to migrate to the Central Publisher Portal in order to utilize this service.

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.

If you are migrating from OSSRH, you should be able to update your plugin's configured URL to point to this service instead of OSSRH and then generate a token from the Portal.

If you automatically closed your repositories via the API, you should be completely set up with just those changes. If your workflow required logging in to the OSSRH UI to release, you may need to add a call to an endpoint to manually complete the upload process to the Portal.

Plugins Tested For Compatibility

We have tested this service with the following plugins:

• gradle-nexus/publish-plugin
• Gradle's built-in maven-publish plugin *
• Maven's built-in maven-deploy plugin *

* Requires using the manual endpoints documented below

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.

Configuration

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/"))
        }
    }
}
// ...

while 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/"
        }
    }
// ...

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.

Deploying

Once you have adjusted your configuration, you should be ready to deploy via the OSSRH Staging API. If your specific plugin releases all the way to Maven Central, you should not require further adjustments to your deployment process. If your plugin opens and closes a staging repository, you will need to navigate to https://central.sonatype.com/publishing/deployments in order to perform the manual release instead of the OSSRH server you previously used.

Deployments not available in the UI

If your process does not use the Nexus Repository Manager 2 Staging APIs, you will need to utilize the manual API endpoints to upload your deployment from the OSSRH Staging API Service to the Central Publisher Portal.

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 the release of the closed 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.

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.