Publishing to Maven Central

Since 2025-06-30 there is one way in for open source releases: the Central Publisher Portal at central.sonatype.com, which replaced the OSSRH service (see "The end of OSSRH" below). A release travels like this:

Three things in that picture are the whole page. The build must produce more than a JAR: a POM with complete metadata, a sources JAR, a Javadoc JAR and a signature for every file. The Central Publishing plugin turns what the build produced into a bundle and sends it. And the Portal validates the bundle, and, only when it is valid and has been released, copies it into Central, where it can never be changed (Central does not replace or remove a published release). A release that fails validation is not published and can be dropped.

The build tools differ only in the first two steps. Ant, Gradle and Maven all end in the same bundle format; the cross-tool view, including the raw curl call to the Publisher API, is on Repositories & Publishing Across Tools. Gradle and Android projects publish with a community plugin and are on Gradle: Publishing and Android Libraries & Maven Central. How mvn install and mvn deploy work in general, and the distributionManagement that the Central plugin does not use, is on Install, Deploy & Distribution Management; the version bumping and tagging that precede a publication are on Releasing.

Central checks every deployment against these rules. The right column says where in a Maven build each one comes from.

Source: Central: Requirements, Javadoc and sources, checksums, signatures and POM metadata; Central: Register a Namespace; Maven: Guide to uploading artifacts to the Central Repository.

The next sections take the build part first, one requirement at a time, and the Portal part afterwards.

The tidepool parent POM carries all the metadata, and the modules inherit it. The module POMs add only their own description:

Composing the name from the coordinates, as here, is an accepted practice that avoids writing a name per module. The scm URLs have to be present but need not be public; the developer entry may link a profile page if you have no website. The <tag> records the release tag and is what the release plugin updates (see Releasing).

Maven does not check any of this. A build that lacks the licence and the scm section succeeds, signs, bundles and (in the real world) uploads, and it is the Portal that rejects it afterwards. To see the difference in a local run, the copy of the project without those two elements was built with -DskipUpload=true (the option is explained below) and the resulting bundle was inspected with the pre-flight script from the section "A local pre-flight check". The Maven build itself ended with BUILD SUCCESS:

Source: Central: Required POM metadata

The POM that Central keeps is the one in the bundle. Maven 3 deploys the file you wrote, with parent and ${project.version} references intact, so the parent POM must be in the same bundle (or already on Central), which is why the tidepool bundle holds three POMs. Maven 4 (release candidate) additionally builds a flattened consumer POM; how that interacts with publication is on Maven 4: POM Model & Consumer POM.

A project with Java sources must ship tidepool-model-1.0.0-sources.jar and tidepool-model-1.0.0-javadoc.jar next to the main JAR. The two plugins attach them to the build, so that install, deploy and the Central plugin treat them as part of the project:

source:jar-no-fork is the goal to bind: source:jar would fork its own generate-sources lifecycle and build the project a second time. The Javadoc goal is javadoc:jar, which runs the JDK javadoc tool and packs the result. Both are bound to the default phases of their goals (package), after the main JAR. The versions are pinned in pluginManagement, as every plugin version should be (see Maven Plugins & Their Configuration).

Source: Source Plugin: source:jar-no-fork and Javadoc Plugin: javadoc:jar

Where the plugins live in the POM is a design choice. Putting them in the main <build> makes every mvn package slower by the Javadoc run; putting them in a profile that only the release activates keeps the daily build fast. tidepool uses a profile named release, which the whole page builds up (the complete profile is shown in the section "The Central Publishing plugin"). Profiles are on Maven Profiles. The effect is visible in the module’s target directory. With no profile Maven 3.10.0 builds only the JAR; with -Prelease it builds the two extra JARs and the signatures that the next section adds:

Source: Maven: Introduction to Build Profiles, Explicit profile activation

Central requires the signature of every file, and a signature only means something if a consumer can find your public key. The key pair is created once, with GnuPG; the secret half signs your releases, the public half goes to a keyserver. Central lists keyserver.ubuntu.com, keys.openpgp.org and pgp.mit.edu as the keyservers its servers consult.

The key used on this page is a throwaway generated into a scratch GNUPGHOME, so that the real keyring of the machine is never read or written. Two practical constraints came out of it. The home directory has to be a short path: gpg-agent creates a Unix socket in it and the long scratch path of these runs made key generation fail with can't connect to the agent: File name too long, so the scratch directory was reached through a short symbolic link. And the key was given a one-day lifetime (1d); a real signing key is normally valid for a few years and extended before it expires.

On a workstation you would use gpg --gen-key or gpg --full-generate-key and type the passphrase into the pinentry dialog instead of putting it on a command line. If you have several keys, GnuPG signs with the first signing key it finds; name the one to use with the plugin’s keyname parameter (passed to gpg as --local-user).

The public key then has to be published, so that the Portal and your users can fetch it. The command is the one the Central documentation shows; it was not run here, because it would put the key on a public server for good (a key that has been published to the public keyservers is hard to take back):

What the keyserver is for is easiest to see from the consumer side. The signature file of a real library, commons-csv-1.14.1.jar.asc, was fetched from Central, and verified against its JAR in an empty GnuPG home, first with no key and then after fetching the signer’s key from a keyserver (which only reads from it):

(The output of the first and the second command was shortened: the lines about creating the empty keybox and the trust database were left out.) The warning at the end is normal: a signature proves that the holder of that key signed the file, not who the key belongs to; deciding to trust a key is a separate step that is covered with checksums and dependency verification on Supply Chain Security. An unpublished key is the first reason signatures "fail" on Central: the validator, like this consumer, cannot find a public key.

Keep the secret key and its passphrase out of the repository and out of build logs, keep a revocation certificate (GnuPG writes one to openpgp-revocs.d at generation time), and extend the key with gpg --edit-key before it expires; the Central documentation describes how.

Source: Central: GPG, generating a key pair, distributing your public key and dealing with expired keys

The gpg:sign goal signs the project artifact, the POM and every attached artifact (sources, Javadoc) and attaches the .asc files, so that the next steps of the build carry them along. It is bound to the verify phase, after packaging and before install and deploy:

Source: GPG Plugin: Sign artifacts with GnuPG

The plugin has four goals (gpg:help): sign, sign-and-deploy-file, sign-deployed and help. Its important parameters, as gpg:help -Ddetail -Dgoal=sign reports them for 3.2.8:

org.sonatype.central:central-publishing-maven-plugin (version 0.12.0) replaces the Maven Deploy Plugin for publication to Central. It is added with <extensions>true</extensions>, which lets it hook into the build lifecycle: it observes every module, stages the files of each into a directory, and in the last module of the reactor it adds checksums, zips the staged files into one bundle and sends it. The release profile of tidepool in full:

Source: Central: Publishing with the Maven plugin, usage

The plugin does no signing, no Javadoc and no metadata checking: its documentation says explicitly that it only generates the checksums and that the remaining prerequisites of a valid bundle are the build’s job. There is no <distributionManagement> entry for Central: the plugin knows the Portal URL (centralBaseUrl, https://central.sonatype.com by default).

The effective POM shows what the extension does. help:effective-pom -Prelease on the module lists the plugin with an execution that you did not write, bound to the deploy phase:

The deploy:deploy goal does not run when the extension is active: in the logs of the Central builds on this page there is no deploy:3.2.0:deploy line, while the build with the legacy staging API further down has one per module. A classic mistake is to leave <extensions>true</extensions> out. The plugin then does nothing, the ordinary deploy goal runs, and the build asks for a repository you never configured:

Without skipUpload, the plugin uploads the bundle and then waits. What it waits for, and whether it publishes, is controlled by two settings.

The shortcut for both is to set them as plugin configuration in the POM or as user properties on the command line, but beware of the precedence: a value written in the POM’s <configuration> wins over -D. In the first attempt of this page’s runs the POM had <autoPublish>false</autoPublish>, and -DautoPublish=true was silently ignored; the build waited for a manual release. The final tidepool POM above therefore leaves these two out so that the command line can choose.

All three runs below were against the stand-in on localhost:18765, with -DcentralBaseUrl pointing at it, so the lines come from the real plugin and the answers from the stand-in. The default (manual publication, waitUntil=validated):

What the stand-in saw is the whole conversation of the plugin with the Portal: one upload and a status poll until the state is reached (the userId and orgId query parameters were removed for readability; the polls are five seconds apart, which is why that build took 20 seconds):

autoPublish maps to publishingType=AUTOMATIC and false to USER_MANAGED, the two values of the Publisher API’s publishingType; the states are the Portal’s deploymentState values (PENDING, VALIDATING, VALIDATED, PUBLISHING, PUBLISHED, FAILED). With -DautoPublish=true -DwaitUntil=published:

(The list of packages is the stand-in’s answer; the plugin turns each pkg:maven/... entry of the real status response into a URL under repo1.maven.org. The published state is the Portal’s, not a promise about how soon mirrors and search indexes show the release.) And when validation fails the build fails, with the errors of the Portal printed. The stand-in’s message is its own, but the format (a header, the component, the list of messages) and the failing build are the plugin’s:

A failed deployment is not published. Fix the cause, then drop the failed deployment in the Portal (or with the DELETE /api/v1/publisher/deployment/<id> call), and run the build again. Do not drop a failed deployment you want Central support to look at.

Source: Central: Automatic publishing, wait for publishing, waitUntil and Publisher API: deployment states

The extension collects every module of the reactor into one bundle, so one mvn deploy publishes the whole group as a single deployment. That matters for two reasons. A module POM refers to its parent POM, and a release is valid only if everything it refers to is on Central or in the same bundle. And the bundle is one deployment, validated and published as a whole.

Not every module belongs on Central: a module of integration tests, an application, an example. The module’s own plugin configuration decides. With <skipPublishing>true</skipPublishing> in the central-publishing-maven-plugin configuration of tidepool-engine, the whole build ran and ended with BUILD SUCCESS, and the bundle had 30 files instead of 54, for the parent and the model only:

The other tools are excludeArtifacts (by artifactId, from the plugin configuration or the command line) and ignorePublishedComponents for the case "release version 1.0.1 of one module and leave the others": the Portal refuses a bundle that contains a component already published, and this option leaves such components out. Remember that the other modules of the reactor must still resolve against what is already on Central. The reactor, its order and -pl/-am are on Multi-Module Builds & the Reactor.

Snapshots are published separately. Central accepts them only for namespaces where snapshots have been enabled, validates nothing, and removes them after a period (currently 90 days). The plugin, from version 0.7.0, handles them: a -SNAPSHOT version is not zipped but uploaded to the location for snapshots (centralSnapshotsUrl, or, if that is not set, the snapshotRepository of distributionManagement). With skipUpload the artifacts are staged but not deployed. A copy of tidepool at version 1.1.0-SNAPSHOT built with -DskipUpload=true:

No bundle is built for a snapshot. Consumers add the snapshot repository https://central.sonatype.com/repository/maven-snapshots/ to their POM with releases disabled and snapshots enabled (repositories are on Repositories, Mirrors & Repository Managers; the general rules for snapshots are on Versions, Snapshots & Ranges). Enabling snapshots for a namespace is done in the Portal and was not run here; a real snapshot deployment was not attempted.

Source: Central: Publishing SNAPSHOT releases

Maven 3.10 needs plugin 0.12.0. Its release notes list as the first fix that deployments were "rejected by Central when built with Apache Maven 3.10.0" with the error Bundle has content that does NOT have a .pom file, because the two kinds of local-repository files above were not removed before the ZIP was created. This was reproduced by running the previous release, 0.11.1, on Maven 3.10.0 against the stand-in, which saves the bundle it receives. The bundle had 72 files instead of 54, the extra 18 being:

The pre-flight script flagged all of them as "local-repository leftover". Whether Central’s own message is the quoted one was not run here; the evidence is the extra files and the release notes. The consequence: when you move a project to Maven 3.10, move the plugin to 0.12.0 or later in the same change. The version in the tidepool POM is a property (central.publishing.version) only so that this experiment could switch it from the command line.

Maven 4 (release candidate) is not supported by the plugin yet. The plugin’s documentation lists "Publishing doesn’t work when using Maven 4.x.x" as a known issue. On 4.0.0-rc-7 the extension announces itself (Installing Central Publishing features, Inspecting build with total of 3 modules), the GPG plugin signs (including the consumer POMs that Maven 4 builds), and the build ends in BUILD SUCCESS, but there is no central-publishing:publish line, no deploy line, no bundle, and the stand-in received no request at all. A successful build that published nothing is the dangerous part: if you run Maven 4 builds, check for the Uploaded bundle successfully or the bundle path in the log before you trust a release. Maven 4’s own changes are on Maven 4: Lifecycle and Migrating to Maven 4. The GPG plugin works on all three.

JDK 26 prints three WARNING: Final field artifactRepositoryFactory ... has been mutated reflectively lines at the start of the Central plugin’s first module, from the dependency-injection library Maven uses; they are noise and did not affect any run.

Source: Central plugin release notes and known issues

Until 2025-06-30 projects published to Central through OSSRH, the Sonatype Nexus service at oss.sonatype.org and s01.oss.sonatype.org, with the nexus-staging-maven-plugin or the Maven Deploy Plugin and a staging repository that you "closed" and "released". OSSRH reached end of life on 2025-06-30 and was shut down; the namespaces were migrated to the Portal, where the old account can log in. Every book, blog post and POM that has <repository> entries for oss.sonatype.org (and the ossrh server id that went with them) describes a service that is gone; the nexus-staging-maven-plugin stanza with <serverId>ossrh</serverId> has no server left to talk to. The modern replacement is the Central Publishing plugin of the previous sections.

For projects that cannot change their build quickly, the Portal offers the OSSRH Staging API, a compatibility service that translates a subset of the Nexus 2 staging API to the Portal. You replace the OSSRH host with https://ossrh-staging-api.central.sonatype.com and the OSSRH token with a Portal user token (an OSSRH token gets a 401). Two kinds of plugins are distinguished:

The shape of the Maven-API-like flow was run with the stand-in answering PUT as the staging repository. The release build, with the Central plugin removed from the profile, deployed to the central-staging server of settings.xml through the altDeploymentRepository property of the Deploy Plugin:

(These are the stand-in’s log lines, 45 PUT requests for the three modules, abridged to part of tidepool-model.) Note that nothing in them says "this release is complete". The last step, the manual call, is a plain authenticated request; it was sent to the stand-in, which only acknowledged it with HTTP 200, so the real service was not tried:

The Bearer value is the Base64 encoding of username:password of the token. The compatibility service is a bridge: its documentation states the hope that plugins will adopt the Portal API, its repositories are per user and, for the Maven-like API, isolated by IP address, and the Central Publishing plugin needs none of that.

Source: Central: OSSRH Sunset, Staging API: Maven-API-like plugins, Nexus 2 API plugins and known limitations

The pieces above fit together in a release job like this, which was not run as a whole against Central:

CI workflow examples for GitHub Actions are on CI/CD for Android with GitHub Actions and JMeter CI/CD with Maven, Docker & GitHub Actions; keeping credentials out of the repository is also on settings.xml & Password Encryption, and build reproducibility and signing from the consumer’s point of view are on Security & Reproducible Builds. The tidepool parent POM sets project.build.outputTimestamp so that the JARs of two builds of the same tag are byte-identical, which is what makes the signatures reproducible-build friendly.