Nexus Repo Staging - v2 to v3 Upgrade

Repository Manager | Reading time: 9 minutes

Is this article helpful?

In this guide:


In this article, we’ll highlight the change in staging implementation between Nexus Repository Manager 2 and 3. We’ll then go over how you can migrate your data and processes.


This topic is written for Nexus Repository Pro Admins upgrading from version 2 to 3.

Desired Outcomes

By the end of this guide you’ll be able to:

  • Understand staging and identify differences in the staging feature from Nexus Repository versions 2 and 3.
  • List the benefits of tagging and staging in Nexus Repository 3.
  • Be able to move from the staging suite in Nexus Repository 2 to the REST API setup in Nexus Repository 3.
  • Troubleshoot possible pain points and identify best practices for your enterprise.

What is Staging?

In Nexus Repository Manager (NXRM) Pro, staging is a means to model, control, and track the promotion of artifacts from development to production. Staging allows your organization to have some sequence of hosted repositories and move or promote components through those repos in accordance with your delivery or code promotion process. Other features of staging in Nexus Repository Pro let you:

  • Avoid exposing your entire organization to untested components.
  • Identify a batch of components as a “build.”
  • Track build status from development to production.
  • Apply rules to builds (e.g. no SNAPSHOT dependencies).
  • Control build visibility based on status.

Staging can also answer the question of “What made it to production?” This lets you create isolated release candidates that can be promoted or discarded in support of certifying a release.

Staging in Nexus 2 vs. Nexus 3

In Nexus Repository 2, staging is done through the staging suite, while in Nexus Repository 3 staging is done through tagging and REST API calls. This difference means that upgrading from Nexus Repository 2 to 3 lets you go from a dynamic repo based model to a tag-based model.

When designing staging in NXRM 3, the Sonatype Nexus Repo team had a chance to look for areas of improvement in NXRM 2 and then develop the new staging feature to mitigate these issues.

Some of the issues identified in NXRM 2 staging were:

  • It only works for the maven2 format.
  • Deployment/approval workflows are increasingly external to NXRM.
  • It doesn’t scale. Failing to apply proper housekeeping controls means there can be 1000’s of repositories, leading to significant performance problems in NXRM 2.
  • It’s easy to lose track of build identity after promotion (the staging repo goes away).

The Nexus Repo team worked to resolve these issues and develop features in Nexus Repository Manager 3 that let you:

  • Administer access control to in-house components at different phases of the SDLC. Components can be restricted until fully tested.
  • Store components in a single hosted repository for each stage, while identifying individual builds and managing retention periods by stage.
  • Move components between release stages using the REST API.
  • Associate custom metadata to builds as components are uploaded to the repository.
  • Manage workflows with external CI/CD tools.

A side by side comparison:

Staging in Nexus Repo 2 Staging in Nexus Repo 3
Workflow defined in Nexus Repo Workflow defined externally (i.e. Jenkins)
Each build is a separate repository Each build is a tag
Hundreds of repositories accumulate Small, fixed number of repositories
Builds are absorbed into release repo Build metadata outlives promotion
UI Driven Powered by REST, no UI
Maven2 only Maven2, raw, Docker, npm, Nuget, YUM
Rules defined in NXRM 2 Rules invoked externally by CI/CD
“Staging” is a feature Toolkit APIs used to build staging

Keep in mind that the staging feature in NXRM 3 has been completely redesigned and is not compatible with NXRM 2 staging. NXRM 3 staging provides a set of flexible building block capabilities that can be combined and arranged as needed to accommodate your organization’s software build and release pipeline. The set of REST endpoints that expose these capabilities allow for easy integration into CI/CD systems, and are easily customized to the workflows or client tooling and technologies needed to interact with them.

Benefits of Tagging and Staging in NXRM 3

There are several advantages to upgrading to Nexus 3, and we’ll go over some of them here.

Flexible Workflow

Staging is a set of powerful REST endpoints that are highly customizable to your environment. This new implementation makes build deployment configuration more flexible for teams as they expand beyond CI server usage to the staging repository and the ability to dynamically select builds for promotion.

Staging for NXRM 3 also helps empower teams to take control of the build deployment process using advanced metadata capabilities. This includes deciding how the metadata changes along the release workflow, as well as how to isolate the right builds for the right teams.


Staging also works closely together with our tagging feature. In Nexus Repository Manager Pro, staging works by moving components across hosted repositories. For instance, you could have hosted repositories for Dev, UAT, and Production. You can then promote software components matching your organization’s software development lifecycle phases by moving components between these hosted repositories. This is where the tagging feature comes in. Tagging in Nexus Repo 3 is more powerful because you can easily group multiple builds and promote them as if they were a single unit.

For example, a complex project like Nexus Repository Manager has thousands of files and all sorts of components that go into a build. The Nexus Repo teams needs a way to take all of these components that span multiple different coordinates and group them together in a way that lets us know it’s a single build. You can use the tagging REST endpoints to create and delete tags, list all tags, and attach metadata to tags. This is the Nexus 3 equivalent to custom metadata.

As you can see from the example above, using tags provides a way to group and move your artifacts. Nexus Repo 3 provides several means for tagging, which usually happens on upload, but can also be done after upload as well. You can tag components with your automated CI/CD processes using the Jenkins Platform plugin. Alternatively, you can also tag components during upload within the UI.

Path from 2 to 3

Now that you understand how staging in Nexus Repo 3 works, the next step is redefining your process from Nexus Repository 2 to the new instance. Upgrading to Nexus 3 will give you a staging feature with a set of extremely configurable building blocks that can be adapted to your organization’s needs.

Although there is no direct upgrade path from Nexus Repo 2 to 3, this section will go over some steps you can take to get started.

A basic setup workflow for staging in Nexus Repo 3 might look something like this:

  1. Ensure that your upgrade from NXRM 2 to NXRM 3 is complete.
  2. Identify the staging workflow from your Nexus Repo 2 configuration.
  3. Create matching hosted repos in Nexus Repo 3.
  4. Incorporate the stages of your agile software development lifecycle into the Nexus Platform plugin for staging.
  5. Add a tagging call to the build.
  6. Update the Nexus Repo 2 Maven calls to the Nexus Repo 3 REST calls.
  7. Associate custom metadata to tags. Custom information is an extension of tagging. See for more info.
  8. Use the Move REST API endpoint to promote tagged components among the hosted repos.
  9. Use the Delete REST API endpoint to delete tagged components among the hosted repos.
  10. Run a cleanup task to delete tags you no longer need.

The above steps represent a basic scenario. Our REST APIs give you a lot of flexibility to make this more robust and well integrated into your CI/CD pipeline.

For more information on our staging workflow, please see the staging and tagging topics in our help documentation.

Best Practices and Troubleshooting

Although migration from NXRM 2 staging to NXRM 3 staging is not supported, there are a few things you can do to make the move easier. Here are a few ideas to help you make the switch:

  • Keep in mind that this is an opportunity to start fresh with a new set of features that are compatible with modern CI/CD pipelines.
  • Review what worked in Nexus Repo 2 staging and what didn’t. This can help you determine what needs to be implemented similarly and where there are areas for improvement.
    • For example, you may need to keep your Nexus 2 staging repos for data retention purposes. These types of requirements should be taken into account.
  • When you upgrade, any “in flight” staging repositories in Nexus Repo 2 are not migrated, meaning upgraded components in a build promotion repo or staging repo are not moved. This is an important setup step that should be thought about prior to upgrade.
  • Get familiar with concepts and terminology, e.g:
    • Tag names are a string (or label) that are the primary key for what gets “staged.”
    • Metadata is extra information.
    • You cannot stage or create permissions based on metadata.
  • Invest your time in establishing a strategy for naming tags and your management approach for tags. For example, think about things like:
    • Will tags be used? (This may depend on your organization’s approach to naming builds and repos).
    • How will tags be routinely aged off?
    • What is the best way to implement tag creation and assignment to your artifacts?
  • Keep in mind the benefits of staging in Nexus Repo 3:
    • You can control who can see in-house components at different parts of the SDLC, so they aren’t used before they’re ready.
    • You can batch components together and easily identify builds.
    • Stagings REST APIs are powerful and flexible.
    • You can control the workflow from your CI/CD pipeline.
    • The “toolkit” style implementation means it supports other use cases.
    • Maven and Jenkins integration - e.g. automatically tested, manually tested, signed, approved, etc.

Additional Resources

Go over to Sonatype Help to read our help topics on Staging and Tagging in Nexus Repository Manager 3.

Talk to Us

Have more questions or comments? Learn more at, join us in the Sonatype Community, and view our course catalog at

And visit for all things Sonatype.