Repository files navigation

A gradle plugin providing tasks to close and promote/release staged repositories. It allows to do a full artifacts release to Maven Central throughSonatype OSSRH (Open Source Software Repository Hosting) without the need to use Nexus GUI (to close and releaseartifacts/repository).

IMPORTANT. To make releasing to Maven Central even easier, I and Marc Phillip (the author of nexus-publish-plugin) combined forces to create a next generation, unified, 2-in-1 plugin -gradle-nexus-publish-plugin. It is a recommended solution, as our development effort will be put in that new plugin. See myblog post and the officialmigration guide.

Thank you for over 5 years of releasing with my plugin!

Add gradle-nexus-staging-plugin to thebuildscript dependencies in your build.gradle file for root project:

buildscript {    repositories {        mavenCentral()        //Needed only for SNAPSHOT versions        //maven { url "http://oss.sonatype.org/content/repositories/snapshots/" }    }    dependencies {        classpath "io.codearte.gradle.nexus:gradle-nexus-staging-plugin:0.30.0"    }}

Apply the plugin:

apply plugin: 'io.codearte.nexus-staging'

Configure it:

nexusStaging {    serverUrl = "https://s01.oss.sonatype.org/service/local/" //required only for projects registered in Sonatype after 2021-02-24    packageGroup = "org.mycompany.myproject" //optional if packageGroup == project.getGroup()    stagingProfileId = "yourStagingProfileId" //when not defined will be got from server using "packageGroup"}

After successful archives upload (withmaven,maven-publish ornexus plugin) to Sonatype OSSRH call:

./gradlew closeAndReleaseRepository

to close staging repository and promote/release it and its artifacts. If a synchronization with Maven Central was enabled the artifacts shouldautomatically appear into Maven Central within several minutes.

In addition to Maven Central the plugin is available also from thePlugin Portal and (in most cases) can be applied in a simplified way:

plugins {    id 'io.codearte.nexus-staging' version '0.30.0'}

Buildscript andapply plugin sections can be ommited in that case.

The plugin itself does not upload any artifacts. It only closes/promotes a repository with all already uploaded using themaven ormaven-publish plugin artifacts (in the same or previous Gradle execution). Therefore it is enough to applyio.codearte.nexus-staging only on the root project in a multi-project build.

Struggling with errors while releasing from Travis? Seethis FAQ point for explaination andmy blog post for sample configuration.

The plugin provides three main tasks:

• closeRepository - closes an open repository with the uploaded artifacts. There should be just one open repository available in the stagingprofile (possible old/broken repositories can be dropped with Nexus GUI)
• releaseRepository - releases a closed repository (required to put artifacts to Maven Central aka The Central Repository)
• closeAndReleaseRepository - closes and releases a repository (an equivalent tocloseRepository releaseRepository)

And one additional:

• getStagingProfile - gets and displays a staging profile id for a given package group. This is a diagnostic task to get the value and put itinto the configuration closure asstagingProfileId.

It has to be mentioned that calling Nexus REST API ends immediately, but closing/release operations takes a moment. Therefore, to make it possibleto callcloseRepository releaseRepository together (or usecloseAndReleaseRepository) there is a built-in retry mechanism.

Deprecation note. Starting with version 0.8.0promoteRepository andcloseAndPromoteRepository are marked as deprecated and will be removedin the one of the future versions.releaseRepository andcloseAndReleaseRepository can be used as drop-in replacements. The reasons behind thatchange can be found in the correspondingissue.

The plugin defines the following configuration properties in thenexusStaging closure:

• serverUrl (optional) - the stable release repository URL - by default Sonatype OSSRH -https://oss.sonatype.org/service/local/

Important - Users registered in Sonatype after 24 February 2021 need to customize the server URL:serverUrl = "https://s01.oss.sonatype.org/service/local/"

• username (optional) - the username to the server
• password (optional) - the password to the server (an auth tokencan be used instead)
• packageGroup (optional) - the package group as registered in Nexus staging profile - by default set to a project group (has to be overriddenif packageGroup in Nexus was requested for a few packages in the same domain)
• stagingProfileId (optional) - the staging profile used to release given project - can be get with thegetStagingProfile task - when not setone additional request is send to the Nexus server to determine the value usingpackageGroup
• numberOfRetries (optional) - the number of retries when waiting for a repository state transition to finish - by default20
• delayBetweenRetriesInMillis (optional) - the delay between retries - by default2000 milliseconds
• repositoryDescription (optional) - staging repository description in close/release operations (see#63 for more information)
• stagingRepositoryId (optional, since 0.20.0) - the explicitly created staging repository with artifacts to improve build reliability -requires external mechanism (e.g.nexus-publish-plugin) to enhance a Gradle taskto use it for uploading/publishing artifacts (see#77)

For the sensible configuration example see the plugin's own releaseconfiguration.

Production Nexus instances usually require an user to authenticate before perform staging operations. In the nexus-staging plugin there are fewways to provide credentials:

• manually set an username and a password in thenexusStaging configuration closure (probably reading them from Gradle or system properties)
• provide the authentication section inMavenDeployer (from the Gradlemaven plugin) - it will be reused by the nexus-staging plugin
• set the Gradle propertiesnexusUsername abdnexusPassword (via a command line or~/.gradle/gradle.properties) - properties with thesenames are also used bygradle-nexus-plugin.

The first matching strategy win. If you need to set an empty password use'' (an empty string) instead of null.

There may be a few reasons to get this.

1. Ensure using theNexus UI that there are no old open staging repositories from the previous executions. If yes, justdrop them suing the UI and try again. This is quite common during the initial experiments with the plugin.

2. It takes some time to close and/or promote a staging repository in Nexus, especially with multiple artifacts. The plugin has a built-in retrymechanism, however, the default value can be toolow, especially forthe multiproject build. To confirm that enable logging at the info level in Gradle (using the--info or-i build parameter). You should see logmessages similar toAttempt 8/8 failed.. If yes, increase the timeout using thenumberOfRetries ordelayBetweenRetriesInMillis configurationparameters.

3. An another reason to get the aforementioned error is releasing more than one project using the same Nexus staging repository simultaneously(usually automatically from a Continuous Delivery pipeline from a Continuous Integration server). Unfortunately Gradle does not provide a mechanismto track/manage staging repository where the artifacts are being uploaded. Therefore, it is hard to distinguish on closing the own/current repositoryfrom the one created by our another project. There is anidea how it could behandled using the Nexus API. Please comment in thatissue if you are in thatsituation.

4. You are releasing from Travis. See the next point.

If your Travis build started to fail around autumn 2018 it's probably a problem reported in#76.To cut a long story short:

• Gradle doesnot support uploading/publishing to explicitly created staging repositories in Nexus
• gradle-nexus-staging-plugin had been using heuristics to find the right implicitly created staging repository in Nexus (which - with some limitations -worked fine in most cases)
• Travis changed their infrastructure in autumn 2018 whichresultedin using different IP addresses for the same build and - as a result - creation of multiple implicitly created staging repositories on upload/publishing for the same build
• Marc Philipp creatednexus-publish-plugin to enhance publishing in Gradle which seamlesslyintegrates with gradle-nexus-staging-plugin and "fixes" a problem

For releasing from Travis (and in general) it's recommended to addnexus-publish-plugin to your projectand use itspublishToNexus task to upload/publish artifacts to Nexus (instead of vanillapublish... from Gradle). It integrates seamlessly withgradle-nexus-staging-plugin to release to Maven Central (especially with 0.20.0+) - noother changes are required. What's more, with thatenhancement implemented the releasing to Nexus will be even more reliable(e.g. an ability to run multiple releases for the same staging profile). Seemy blog post for sample configuration.

However, there is one caveat.uploadArchives from themaven plugin isnot supportedby nexus-publish-plugin (onlypublish... frommaven-publish).

First thing is to make sure that your credentials are correctly set, using one of the methods explained in theServer Credentials section.

If your credentials are correct and you still get this error, most likely it is happenning because the repository server for you account is different. As of 24 February 2021, accounts created after this date are assigned to a new nexus repository server (https://s01.oss.sonatype.org/).

To fix this, you need to setserverUrl = "https://s01.oss.sonatype.org/service/local/" on thenexusStaging block on your gradle build file.

The plugin is used byhundreds of projects around the web.

Just to mention a few FOSS projects which leverage the plugin to automatize releasing and Continuous Delivery:Frege,Geb,Grails,Javers,JSON Assert,logback-android,Micronaut,mini2Dx,Nextflow andTestNG.

The plugin is also used by the tools and the libraries created by various more or less known companies including:Allegro,Braintree,Google,IBM,PayPal,Schibsted Spain,TouK andZalando.

gradle-nexus-staging-plugin was written by Marcin Zajączkowskiwith the help of thecontributors.The author can be contacted directly via email:mszpak ATT wp DOTT pl.There is also Marcin's blog available:Solid Soft - working code is not enough.

The PoC leading to the initial version of the plugin was brought to life during one of the hackathons held atCodearte.

The first version of the project has been released in 2015 and the plugin seems to be quite stable. Nevertheless, documentation for the Nexusstaging REST API and in addition Gradle support for uploading artifacts to selected Nexus staging repositories leaves much to be desired.Therefore, the current plugin version is still before 1.0.0.

The projectchangelog.

The plugin is licensed under the terms ofthe Apache License, Version 2.0.