Skip to main content

Configuring Your Project for Deployment (Nexus Repository 2)

Nexus Repository 2

Once the repository manager is configured to receive components in the staging suite as documented in Configuring the 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 Deployment with the Nexus Staging Maven Plugin and 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 staging suite in Deployment with the Maven Deploy Plugin.

With all tools you can use the manual upload of your components documented in Manually Uploading a Staged Deployment.

Deployment with the Nexus Staging Maven Plugin

The Nexus Staging Maven plugin is a specific and more powerful replacement for the Maven Deploy plugin with a number of features specifically geared towards usage with the 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 Repository Manager Pro server. Version 1.2 is compatible with Nexus Repository Manager Pro 2.3, Version 1.4.4 is compatible with Nexus Repository Manager Pro 2.4, Version 1.4.8 is compatible with Nexus Repository Manager Pro 2.5 and 2.6. 1.5 and 1.6.x can be used for Nexus Repository Manager Pro 2.7 to 2.10. The latest version of the plugin available is always compatible with the latest available version of Nexus Repository Manager Pro. 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 life cycle 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 the repository manager should be retrieved.


The base URL at which the repository manager to be used for staging is available.

With this configuration the Nexus Staging Maven plugin will stage the components locally and connect to the repository manager. It will try to determine the appropriate staging profile by matching the component 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 components are deployed into it. If no profile is found, the upload will fail.

To successfully deploy to your repository manager, 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 below:

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 deployment user - "deployment123". You should change this password to match the deployment password for your repository manager.

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 shown in the example below:

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 scenario 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 the example pom.xml for Nexus Staging Maven Plugin below:

Full example pom.xml for Nexus Staging Maven Plugin usage

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

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

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

  • Components 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 components to:
[INFO] * Upload of locally staged components 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 is set to true is passed to the plugin execution, the remote staging repository will not be closed.

Instead of repository manager 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 components go through the staging workflow together. An alternative to this approach would be to create an aggregating project that assembles all components 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 components 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 components are released these tags are transformed into attributes stored along the components 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 behavior 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 Nexus IQ Server-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. In multi-module builds the staging of all components is performed in the last module based on the reactor order. If this property is set to true in the module, all staging will be skipped. You have to ensure that this property evaluates as true in the last module of the reactor. If necessary, you can add a dummy module.


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 .


When true , bypass all staging specific features. Remote deploys happen inline at deploy phase of each module, not at build end. The deployment repository is "sourced" from pom.xml <distributionManagement>. Which distribution repository is used depends on the project having a release or snapshot version. Essentially this option makes the staging plugin execution act like the default maven-deploy-plugin. The default setting is false.


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 Nexus IQ Server integration.


The default of 3 seconds can be changed if larger pauses between progress polls for staging operations are desired.

With skipRemoteStaging is 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 components 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 can 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:


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 -

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


Also, you may supply a description like this:

-DstagingDescription="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 favor of the remote control goals of the Nexus Staging Maven plugin.

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 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 documentation 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 targeting 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 repository manager 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 components 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 documentation examples project.

Similarly, you can create a target that releases the staged components 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 Nexus IQ Server integration.


The default of 3 seconds can be changed if larger pauses between progress polls for staging operations are desired.

Deployment with the Maven Deploy Plugin

When using the Maven Deploy plugin with the staging suite, you rely on implicit matching of the components 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 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 therepository 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 a component 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 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: 'component com.sonatype.sample:staging-test'
could not be found on repository: nexus, so will be created
[INFO] Uploading repository metadata for: 'component com.sonatype.sample:staging-test'
[INFO] ------------------------------------------------------------------------

If the staging suite is configured correctly, any deployment to the staging URL matching 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 via the 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.

Deployment and Staging with Gradle

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

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

Manually Uploading a Staged Deployment

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


Figure 11.10. Manually Uploading a Staged Deployment

To upload a component, click on Select Artifact(s) for Upload… and select an components from the filesystem to upload. Once you have selected a component, you can modify the classifier and the extension before clicking on the Add Artifact button. Repeat this process to upload multiple components 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 components, you can then configure the source of the Group, Artifact, Version (GAV) parameters.

If the component 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 components being uploaded. If you would prefer to set the Group, Artifact, and Version identifiers from a POM file that was associated with the uploaded component, 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 components with the same Group, Artifact, and Version identifiers. For example, if you need to upload multiple components 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 component, which is documented in more detail in Artifact Bundles.

Once a staging component upload has been completely configured, click on Upload Artifact(s) button to begin the upload process. The repository manager will upload the components to the Staging URL which will trigger any staging profiles that are activated by the upload by explicitly 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 Managing Staging Repositories.