Gradle Nexus Staging plugin

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

MAINTENANCE MODE

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 my blog post and the official migration guide.

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

Quick start

Add gradle-nexus-staging-plugin to the buildscript 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 (with maven, maven-publish or nexus 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 should automatically appear into Maven Central within several minutes.

New plugin syntax

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

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

Buildscript and apply plugin sections can be ommited in that case.

Multi-project build

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

Travis configuration

Struggling with errors while releasing from Travis? See this FAQ point for explaination and my blog post for sample configuration.

Tasks

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 staging profile (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 to closeRepository 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 it into the configuration closure as stagingProfileId.

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

Deprecation note. Starting with version 0.8.0 promoteRepository and closeAndPromoteRepository are marked as deprecated and will be removed in the one of the future versions. releaseRepository and closeAndReleaseRepository can be used as drop-in replacements. The reasons behind that change can be found in the corresponding issue.

Configuration

The plugin defines the following configuration properties in the nexusStaging 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 token can be used instead)
• packageGroup (optional) - the package group as registered in Nexus staging profile - by default set to a project group (has to be overridden if 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 the getStagingProfile task - when not set one additional request is send to the Nexus server to determine the value using packageGroup
• numberOfRetries (optional) - the number of retries when waiting for a repository state transition to finish - by default 20
• delayBetweenRetriesInMillis (optional) - the delay between retries - by default 2000 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 task to use it for uploading/publishing artifacts (see #77)

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

Server credentials

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

• manually set an username and a password in the nexusStaging configuration closure (probably reading them from Gradle or system properties)
• provide the authentication section in MavenDeployer (from the Gradle maven plugin) - it will be reused by the nexus-staging plugin
• set the Gradle properties nexusUsername abd nexusPassword (via a command line or ~/.gradle/gradle.properties) - properties with these names are also used by gradle-nexus-plugin.

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

FAQ

1. Why do I get Wrong number of received repositories in state 'open'. Expected 1, received 2?

There may be a few reasons to get this.

1. Ensure using the Nexus UI that there are no old open staging repositories from the previous executions. If yes, just drop 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 retry mechanism, however, the default value can be too low, especially for the multiproject build. To confirm that enable logging at the info level in Gradle (using the --info or -i build parameter). You should see log messages similar to Attempt 8/8 failed.. If yes, increase the timeout using the numberOfRetries or delayBetweenRetriesInMillis configuration parameters.

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 mechanism to track/manage staging repository where the artifacts are being uploaded. Therefore, it is hard to distinguish on closing the own/current repository from the one created by our another project. There is an idea how it could be handled using the Nexus API. Please comment in that issue if you are in that situation.

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

2. Why my release build on Travis suddenly started to fail with wrong number of received repositories...'?

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 does not 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 which resulted in 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 created nexus-publish-plugin to enhance publishing in Gradle which seamlessly integrates with gradle-nexus-staging-plugin and "fixes" a problem

For releasing from Travis (and in general) it's recommended to add nexus-publish-plugin to your project and use its publishToNexus task to upload/publish artifacts to Nexus (instead of vanilla publish... from Gradle). It integrates seamlessly with gradle-nexus-staging-plugin to release to Maven Central (especially with 0.20.0+) - noother changes are required. What's more, with that enhancement implemented the releasing to Nexus will be even more reliable (e.g. an ability to run multiple releases for the same staging profile). See my blog post for sample configuration.

However, there is one caveat. uploadArchives from the maven plugin is not supported by nexus-publish-plugin (only publish... from maven-publish).

3. Why do I get the error 403: Forbidden when trying to close or release the repository?

First thing is to make sure that your credentials are correctly set, using one of the methods explained in the Server 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 set serverUrl = "https://s01.oss.sonatype.org/service/local/" on the nexusStaging block on your gradle build file.

Notable users

The plugin is used by hundreds 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 and TestNG.

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 and Zalando.

Additional information

gradle-nexus-staging-plugin was written by Marcin Zajączkowski with the help of the contributors. 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 at Codearte.

The first version of the project has been released in 2015 and the plugin seems to be quite stable. Nevertheless, documentation for the Nexus staging 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 project changelog.

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