Repository Management with Nexus

11.3. Configuring Your Project for Deployment

Once Nexus is configured to receive artifacts in the staging suite as documented in Section 11.2, “Configuring the Nexus Staging Suite”, you will have to update your project build configuration to deploy to the staging suite.

The preferred way to do this is to take advantage of the features provided by the Nexus staging Maven plugin or the Nexus staging Ant tasks as documented in Section 11.3.1, “Deployment with the Nexus Staging Maven Plugin” and Section 11.3.2, “Deployment with the Nexus Staging Ant Tasks”.

If you need to continue to use the Maven deploy plugin, you can read about using it with the Nexus staging suite in Section 11.3.3, “Deployment with the Maven Deploy Plugin”.

With all tools you can use the manual upload of your artifacts documented in Section 11.3.5, “Manually Uploading a Staged Deployment in Nexus”.

11.3.1. Deployment with the Nexus Staging Maven Plugin

The Nexus staging Maven plugin is a Nexus specific and more powerful replacement for the Maven deploy Plugin with a number of features specifically geared towards usage with the Nexus staging suite. The simplest usage can be configured by adding it to the project build plugins section as an extension:


It is important to use a version of the plugin that is compatible with your Nexus server. Version 1.2 is compatible with Nexus 2.3, Version 1.4.4 is compatible with Nexus 2.4, Version 1.4.8 is compatible with Nexus 2.5 and 2.6. 1.5 and 1.6.x can be used for Nexus 2.7 to 2.10. The latest version of the plugin available is always compatible with the latest available version of Nexus. Try to use the newest possible plugin version to take advantage of any available improvements.

Following Maven best practices, the version should be pulled out into a pluginManagement section in a company POM or parent POM.

This configuration works only in Maven 3 and automatically replaces the deploy goal invocation of the Maven deploy plugin in the deploy Maven lifecycle phase with the deploy goal invocation of the Nexus staging Maven plugin.

The minimal required configuration parameters for the Nexus staging Maven plugin are:

The id of the server element in settings.xml from which the user credentials for accessing Nexus should be retrieved.
The base URL at which the Nexus server to be used for staging is available.

With this configuration the Nexus staging Maven plugin will stage the artifacts locally and connect to Nexus. Nexus will try to determine the appropriate staging profile by matching the artifact path with any repository targets configured with staging profiles with an activated implicit profile selection strategy. If an appropriate staging profile is found, a staging repository is created on the fly and the artifacts are deployed into it. If no profile is found, the upload will fail.

To successfully deploy to your Nexus instance, you will need to update your Maven Settings with the credentials for the deployment user. These credentials are stored in the Maven Settings file in ~/.m2/settings.xml.

To add these credentials, add the following element to the servers element in your ~/.m2/settings.xml file as shown in Listing deployment credentials in Maven Settings.

Listing deployment credentials in Maven Settings. 


Note that the server identifier listed in Listing deployment credentials in Maven Settings should match the serverId parameter you are passing to the Nexus Staging Maven Plugin and in the example contains the default password for the Nexus deployment user - deployment123. You should change this password to match the deployment password for your Nexus installation.

If more control is desired over when the plugins deploy goal is activated or if Maven 2 is used, you have to explicitly deactivate the Maven Deploy Plugin and replace the Maven Deploy Plugin invocation with the Nexus Staging Maven Plugin like visible in in Usage of Nexus Staging Maven Plugin for Maven 2.

Usage of Nexus Staging Maven Plugin for Maven 2. 

        <!-- explicit matching using the staging profile id -->

The implicit matching relies on the setup of repository targets as well as the correct order of staging profiles and is therefore an error prone approach when many staging profiles are in use.

The preferred way to work in this sceneario is to change the profile selection strategy on all staging profiles to explicit only and pass the staging profile ID to the Nexus staging Maven plugin using the stagingProfileId configuration parameter as documented above. A full example pom.xml for deployment of snapshot as well as release builds with the Nexus staging Maven plugin using explicit matching for the staging profile and locally staged builds and atomic uploads is available in Full example pom.xml for Nexus Staging Maven Plugin usage.

Full example pom.xml for Nexus Staging Maven Plugin usage. 




          <!-- update this to the correct id! -->

In order to deploy project artifacts to Nexus with the above setup you would invoke a build with mvn clean deploy.

The build will locally stage the artifacts for deployment in target/nexus-staging on the console and create a closed staging repository in Nexus holding the build artifacts. This execution of the deploy goal of the Nexus staging Maven plugin performs the following actions:

  • Artifacts are staged locally.
  • A staging profile is selected either implicitly or explicitly.
  • A staging repository is either created on the fly, if needed, or just selected.
  • An atomic upload to the staging repository is performed.
  • The staging repository is closed (or dropped if upload fails).

The log of a successful deployment would look similar to this:

[INFO] --- nexus-staging-maven-plugin:1.1.1:deploy (injected-nexus-deploy) @ staging-example ---
[INFO] Using server credentials with ID="nexus-releases" from Maven settings.
[INFO] Preparing staging against Nexus on URL http://localhost:8081/nexus/
[INFO]  * Remote Nexus reported itself as version 2.2.1 and edition "Professional"
[INFO]  * Using staging profile ID "12a1656609231352" (matched by Nexus).
[INFO] Staging locally (stagingDirectory=
Uploading: file: ... explicit-staging-example-1.0.0.jar
Uploaded: file: ... explicit-staging-example-1.0.0.jar (4 KB at 1051.1 KB/sec)
Uploading: file: ... explicit-staging-example-1.0.0.pom
Uploaded: file: ... explicit-staging-example-1.0.0.pom (4 KB at 656.2 KB/sec)
Downloading: file: ...maven-metadata.xml
Uploading: file: ...maven-metadata.xml
Uploaded: file: ... maven-metadata.xml (322 B at 157.2 KB/sec)
[INFO] Staging remotely...
[INFO] Uploading locally staged directory: 12a1656609231352
[INFO] Performing staging against Nexus on URL http://localhost:8081/nexus/
[INFO]  * Remote Nexus reported itself as version 2.2.1 and edition "Professional"
[INFO]  * Created staging repository with ID "test-002",
applied tags: {javaVersion=1.6.0_37, localUsername=manfred}
[INFO]  * Uploading locally staged artifacts to:
[INFO]  * Upload of locally staged artifacts done.
[INFO]  * Closing staging repository with ID "test-002".
[INFO] Finished staging against Nexus with success.

Failures are accompanied by error reports that reveal further details:

[ERROR] Error while trying to close staging repository with ID "test-003".
[ERROR] Nexus Staging Rules Failure Report
[ERROR] ==================================
[ERROR] Repository "Test-003 (u:admin, a:" (id=n/a) failures
[ERROR]   Rule "RepositoryWritePolicy" failures
[ERROR]     * Artifact updating: Repository ='releases:Releases' does
not allow updating
[ERROR]     * Artifact updating: Repository ='releases:Releases' does
not allow updating

If the configuration parameter skipStagingRepositoryClose set to true is passed to the plugin execution, the remote staging repository will not be closed.

Instead of Nexus creating a staging repository based on the implicit or explicit staging profile selection, you can explicitly configure the staging repository to use by providing the staging repository name as value of the stagingRepositoryId configuration property via the plugin configuration or command line invocation.

The identifier of a staging repository can be determined by looking at the name column in the list of staging repositories. The name column used the capitalized ID and adds the username and address the staging was deployed from in brackets. For example a name could be Test-003 (u: admin, a: The ID of this staging repository is test-003.

Together with skipping the closing of the repository using skipStagingRepositoryClose, it is possible to get multiple builds to deploy to the same staging repository and, therefore, have a number of artifacts go through the staging workflow together. An alternative to this approach would be to create an aggregating project that assembles all artifacts together, e.g., in an assembly and then use this project for staging.

Finally to override all staging, you can define the full repository URL to deploy to with the deployUrl configuration parameter. For example, see below:


This would cause any staging to be skipped and a straight upload of the artifacts to the repository to occur.

As part of the configuration section for the plugin you can define tags with arbitrary key and value names. For example, you could create a tag with key localUsername and a value of the current user picked up from the USER environment variable:


Once artifacts are released these tags are transformed into attributes stored along the artifacts in the release repository and can be accessed via the REST interface and, therefore, any plugin and user interface integration.

In addition to the above documented configuration options that determine the behvaiour of the Nexus Staging Maven Plugin, further configuration can be provided with the following parameters:

Defaulting to target/nexus-staging you can set the property to set a different folder for the local staging.
If you set this flag to true, the staging repository will be closed and, following a successful validation of all staging rules including potential Sonatype CLM based validation, released. By default this property is set to false. Changing it to true can be a useful setup for continuous integration server based releases.
Allows you to provide a description for the staging repository action (like close or drop) carried out as part of the plugin execution. The description will then be used in any notification just like a description provided in the user interface.
Setting this flag to true will cause the plugin to skip any clean up operations like dropping a staging repository for failed uploads, by default these clean up operations occur.
With the default setting of false, the Nexus staging Maven plugin will drop the created staging repository if any staging rule violation occurs. If this flag is set to true, it will not drop the staging repository. This allows you to inspect the deployed components in order to figure out why a rule failed causing the staging failure.
Set this to true to turn off the automatic closing of a staging repository after deployment.
Set to false by default, this flag will cause to skip any execution of the deploy goal of the plugin when set to true similar to maven.deploy.skip
Set to false by default this flag will cause to skip any execution of the plugin when set to true.
If this flag is set to true any step related to remote staging will be skipped and only local staging will be performed. The default setting is false.
By default set to true causes the Nexus Staging Maven Plugin to use local staging. Setting this parameter to false turns off local staging, which emulates the immediate upload as performed by the Maven deploy plugin.
Defaulting to 5 minutes, this configuration allows you to set the timeout for staging operations. Changes are most often required for complex staging operations involving custom staging rules or Sonatype CLM integration.
The default of 3 seconds can be changed if larger pauses between progress polls for staging operations are desired.

With skipRemoteStaging set to true, only the local staging happens. This local staging can then be picked up for the remote staging and closing by running the deploy-staged goal of the plugin explicitly like this

mvn nexus-staging:deploy-staged

Besides the default deploy goal the Nexus staging Maven plugin supports a number of additional goals. By configuring executions of the goals as part of your POM or manually invoking them further automation of a staged release process can be achieved.

Perform full staging deployment workflow for a locally staged project, e.g., with the artifacts in target/nexus-staging.
Perform an upload of a repository from the local filesystem to a staging repository.
Close the staging repository for current context.
Drop the staging repository for current context.
Release the staging repository for current context.
Promote the staging repository for the current context.

Closing, dropping, and releasing the staging repository using the goals relies on content of a local staging folder .

Promoting additionally needs the build promotion profile name passed in via the buildPromotionProfileId configuration parameter.

The deploy-staged-repository goal can be used to stage a repository. Typically, a local repository is created with an invocation of the deploy similar to

mvn deploy -DaltDeploymentRepository=local::default::file://path

To deploy this file system repository with the goal, you have to provide the path to this repository with the repositoryDirectory parameter as well as nexusUrl, serverId and stagingProfileId. Optionally you can configure the repository to stage into with stagingRepositoryId. This aggregated command is then be run outside any specific Maven project.

While the above goals need the context of a project with configuration for the Nexus Staging Plugin in the POM file, it is possible to execute staging repository-related tasks without a project as well. The Nexus Staging Maven Plugin offers remote-control goals to control staging in Nexus:

Close a specified staging repository.
Drop a specified staging repository.
Release a specified staging repository.
Promote a specified staging repository.
List all staging repositories.

When invoking these goals outside a project context, you need to have the Nexus staging Maven plugin groupId specified as a pluginGroup in your settings.xml:


In addition, you need to specify all parameters on the command line as properties passed in via -Dkey=value.

At a minimum the required parameters serverId and nexusUrl have to be specified:

 mvn nexus-staging:rc-close -DserverId=nexus -DnexusUrl=http://localhost:8081/nexus

Depending on the goal you will have to configure the staging repositories you want to close, drop or release with


and you can also supply a description like this

-Ddescription="Dropping since QA of issue 123 failed"

For promoting, you need to add the required parameter that specifies the build promotion profile identifier:


A successful remote control drop would be logged in the command line similar to this

— nexus-staging-maven-plugin:1.2:rc-drop (default-cli) @ standalone-pom —
[INFO] Connecting to Nexus...
[INFO] Using server credentials with ID="nexus-releases" from Maven settings.
[INFO] RC-Dropping staging repository with IDs=[test-003]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------

An example usage of the rc-list goal with output is

$mvn nexus-staging:rc-list -DnexusUrl=http://localhost:8081/nexus
[INFO] --- nexus-staging-maven-plugin:1.5.1:rc-list (default-cli) @ standalone-pom ---
[INFO] Connecting to Nexus...
[INFO] Using server credentials with ID="nexus" from Maven settings.
[INFO] Getting list of available staging repositories...
[INFO] ID                   State    Description
[INFO] example_release_profile-1000 OPEN     Implicitly created (auto

The Nexus Maven Plugin in versions earlier than 2.1.0 had goals to work with staging repositories. These goals have been deprecated in favour of the remote control goals of the Nexus Staging Maven Plugin.

11.3.2. Deployment with the Nexus Staging Ant Tasks

The Nexus staging Ant tasks provide equivalent features to the Nexus staging Maven plugin for Apache Ant users covering all use cases for interacting with the Nexus staging suite.

Historically Ant builds typically have components that are required for the build, statically managed in the version control system or even outside the project workspace altogether. More modern Ant builds use Apache Ivy or Eclipse Aether for resolving dependencies dynamically as well as deployment build outputs to a repository manager. Examples projects setups using Ivy as well as Aether can be found in the Nexus book examples project. This project includes examples for integration with the Nexus staging Ant tasks.

To use the Ant tasks in your Ant build file, download the complete JAR with the included dependencies from the Central Repository. Simply search for nexus-staging-ant-tasks and download the JAR file with the uber classifier e.g., nexus-staging-ant-tasks-1.6-2-uber.jar.

After downloading, put the JAR file somewhere in your project or in your system so you can add it to the classpath in your build file with a task definition. In the following example, the JAR file is placed in a tasks folder within the project.

<taskdef uri=""
    <fileset dir="tasks" includes="nexus-staging-ant-tasks-*uber.jar" />

To enable the tasks in your build file using a shortcut for the namespace, e.g., staging, you have to add it to the project node:

<project xmlns:staging="" ...>

The deployment-related information for your project is captured in a nexusStagingInfo section in your build file that contains all the necessary configuration.

<staging:nexusStagingInfo id="target-nexus"
  <staging:projectInfo groupId=""
      version="1.0" />
      password="deployment123" />
The identifier that allows you to reference the staging information in the Ant build file.
The local staging directory, a place where local staging will happen. Ensure that this directory is cleaned up by a clean task or alike, if any.
The project information targetting a staging profile. This can be done explicitly with the stagingProfileId or implicitly with groupId, artifactId and version. stagingRepositoryId can also be part of projectInfo identifying a staging repository for interaction.
The base URL of the Nexus server you want to deploy to and interact with.

If necessary the connectionInfo can have a nested proxy section

      password="proxySecret" />

With the above setup you are ready to add a deploy target to your build file that stages the artifacts locally as well as remotely and closes the staging repository.

<target name="deploy" description="Deploy: Local and Remote Staging">
        refid="target-nexus" />
      <fileset dir="target/local-repo"
        includes="**/*.*" />

        refid="target-nexus" />

The folder target/local-repo has to contain the components in a directory structure resembling the Maven repository format using the groupId, artifactId and version coordinates of the component mapped to directory names. It will be merged into the target release repository, when the staging repository is released. An example on how to create such a structure in Ant can be found in the staging example for Apache Ivy and Eclipse Aether in the Nexus book examples project.

Similarily, you can create a target that releases the staged artifacts by adding the releaseStagingRepository task to the end of the target:

      refid="target-nexus" />

The stageLocally task takes a fileset as configuration. The stageRemotely task has additional configuration options.

Set to true this causes the remote staging repository to be kept rather than deleted in case of a failed upload. Default setting is false
By default a staging repository is automatically closed, setting this parameter to true will cause the staging repository to remain open.

In addition to the tasks for local and remote staging, the Nexus staging Ant tasks include tasks for closing, dropping, releasing and promoting a staging repository:

  • closeStagingRepository
  • dropStagingRepository
  • releaseStagingRepository
  • promoteStagingRepository

All these tasks take the context information from the local staging directory or from the optional parameter stagingRepositoryId. The task to promote a repository has the additional, mandatory attribute buildPromotionProfileId to specify the build promotion profile to promote.

The timing of the task operation can be affected by the following configuration parameters:

Defaulting to 5 minutes, this configuration allows you to set the timeout for staging operations. Changes are most often required for complex staging operations involving custom staging rules or Sonatype CLM integration.
The default of 3 seconds can be changed if larger pauses between progress polls for staging operations are desired.

11.3.3. Deployment with the Maven Deploy Plugin

When using the Maven deploy plugin with the Nexus staging suite, you rely on implicit matching of the artifacts against a staging profile based on a repository target definition.

To deploy a staged release, a developer needs to deploy to the staging URL. To configure a project to deploy to the staging URL, add the a distributionManagement element to your project’s POM.

Listing the Staging URL in distributionManagement. 

<project xmlns=""
      <name>Nexus Staging Repo</name>

This configuration element, distributionManagement, defines the repository to which our deployment will be made. It references the staging suite’s URL: http://localhost:8081/nexus/service/local/staging/deploy/maven2

This URL acts as a virtual repository to be published to. If an artifact being published matches one of the repository targets in a staging profile, that staging profile is activated and a temporary staging repository is created.

Once the sample project’s distributionManagement has been set to point at the Nexus staging URL and your deployment credentials are updated in your ~/.m2/settings.xml file, you can deploy to the staging URL. To do this, run mvn deploy:

$ mvn deploy
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building staging-test
[INFO]    task-segment: [deploy]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] Nothing to compile - all classes are up to date
[INFO] [surefire:test]
[INFO] Surefire report directory: /private/tmp/staging-test/target/surefire-reports

[INFO] [jar:jar]
[INFO] [install:install]
[INFO] Installing /private/tmp/staging-test/target/staging-test-1.0.jar to \
[INFO] [deploy:deploy]
altDeploymentRepository = null
Uploading: http://localhost:8081/nexus/service/local/staging/deploy/maven2/\
2K uploaded
[INFO] Uploading project information for staging-test 1.0
[INFO] Retrieving previous metadata from nexus
[INFO] repository metadata for: 'artifact com.sonatype.sample:staging-test'
could not be found on repository: nexus, so will be created
[INFO] Uploading repository metadata for: 'artifact com.sonatype.sample:staging-test'
[INFO] ------------------------------------------------------------------------

If the staging suite is configured correctly, any deployment to the staging URL matching in a repository target configured for a staging profile should be intercepted by the staging suite and placed in a temporary staging repository. Deployment with the Maven deploy plugin will not automatically close the staging repository. Closing the staging repository has to be done with the Nexus user interface or the Nexus staging Maven plugin. Once this repository has been closed, it will be made available in the target group you selected when you configured the staging profile.

11.3.4. Deployment and Staging with Gradle

The Gradle build system can be used to deploy components to Nexus with the Gradle Maven plugin. The Nexus Staging Ant Tasks can be used in Gradle allowing full inegration of the staging suite features in a Gradle build.

An example project showcasing this integration is available in the Nexus book examples project.

11.3.5. Manually Uploading a Staged Deployment in Nexus

You can also upload a staged deployment via the Nexus interface. To upload a staged deployment, select Staging Upload from the Nexus menu. Clicking Staging Upload will show the panel shown in Figure 11.10, “Uploading a Staged Deployment in Nexus”.


Figure 11.10. Uploading a Staged Deployment in Nexus

To upload an artifact, click on Select Artifact(s) for Upload… and select an artifacts from the filesystem to upload. Once you have selected an artifact, you can modify the classifier and the extension before clicking on the Add Artifact button. Repeat this process to upload mutltiple artifacts for the same Group, Artifact and Version (GAV) coordinates like a JAR, the POM and maybe a sources and javadoc JAR in addition. Once you have added all the artifacts, you can then configure the source of the Group, Artifact, Version (GAV) parameters.

If the artifact you are uploading is a JAR file that was created by Maven, it will already have POM information embedded in it, but if you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition drop-down at the top of this form. Selecting GAV Parameters will expose a set of form fields that will let you set the Group, Artifact, Version, and Packaging of the artifacts being uploaded. If you would prefer to set the Group, Artifact, and Version from a POM file that was associated with the uploaded artifact, select From POM in the GAV Definition drop-down. Selecting From POM in this drop-down will expose a button labeled Select POM to Upload. Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.

The Staging Upload panel supports multiple artifacts with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple artifacts with different classifiers, you may do so by clicking on Select Artifact(s) for Upload and Add Artifact multiple times. This interface also accepts an Artifact Bundle which is a JAR that contains more than one artifact, which is documented in more detail in Section 11.7, “Artifact Bundles”.

Once a staging artifact upload has been completely configured, click on Upload Artifact(s) button to begin the upload process. Nexus will upload the artifacts to the Staging URL which will trigger any staging profiles that are activated by the upload by explicity matching using the repository targets configured with the staging profiles. If a staging profile is activated, a new staging repository will be created and can be managed using the procedures outlined in Section 11.4, “Managing Staging Repositories in Nexus”.