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 and released 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 will need to add a call to an endpoint to manually complete the upload process to the Portal.

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.

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 or automatic

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.

`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 or automatic

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.

`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>"
    }
  ]
}

where the repository state matches the options above and the repository key can be used in the /manual/upload/repository/<repository key> endpoint.

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 are isolated by IP. This matches the Nexus Repository Manager behavior for publishing via the "Maven-like" API, but is a more restrictive limitation than what is supported by the Nexus Repository Manager 2 Staging API.
Staging repositories need to be released 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.