Staging

Only available in Nexus Repository Pro. Interested in a free trial? Start here.

Overview

In modern software development, it is imperative to thoroughly test software before deploying it to a production system or externally accessible repository. Mostly commonly, developers will first deploy a release candidate to a staging system that is a close copy of the production system; here, it will undergo a series of rigorous tests before it is either promoted to production or returned to development. 

The staging functionality in Nexus Repository Pro facilitates this process by allowing you to move components between repositories. This allows you to create isolated release candidates that you can then discard or promote as needed to support the decisions that go into certifying a release.

Building Blocks

Staging comprises three basic building blocks: 

  • Hosted repositories - Upload components/assets to hosted repositories; you can then promote/move them to other hosted repositories or delete them as required. 
  • Component tags - Tag uploaded components/assets so that you can identify them as a logical group and transfer them together. See Tagging for more information.
  • REST endpoints for directly moving and deleting components between hosted repositories.
    • Move - Move all components/assets matching a specific search query to a target repository. 
    • Delete - Delete all components/assets matching a specified search query.

Before using staging in your workflows, review the usage limitations.

Workflow

As depicted in the figure below, a typical staging workflow involves hosted repositories, group repositories to include other dependencies, and an external system that coordinates the promotion process. This usually includes a continuous integration (CI) system (e.g., Jenkins) that continuously builds each commit and a release manager that promotes builds for testing and release.

simple-staging-workflow

The sections below detail each phase of the process as illustrated above.

Build Phase

When a developer pushes new code, the CI system automatically picks it up and performs the build, including any unit or integration tests. It then uploads the resulting artifacts to the incoming NXRM repository. As part of this operation, Nexus Repository tags the artifacts for later identification. The CI project/Job ID and the build ID are often used as the tag. For example, the job project-abc with build ID 142 results in the tag project-abc-build-142.

Test Phase

When ready, you can promote any given build to the next stage. In the figure above, a build is promoted from the incoming hosted repository to the uat repository in preparation for testing. This can be initiated via the CI job/pipeline or as a separate job. NXRM receives the promotion call to take all components tagged with project-abc-build-142 and move them into the uat repository. This repository is then available to a group of users who test the build to ensure quality.

Release Phase

When testing is complete, you can promote the build to the next stage; in the figure above, a build is promoted from the uat repository to the prod repository in preparation for release. Again, this may be initiated via the CI job/pipeline or through a separate job. Nexus Repository receives the promotion call to take all components tagged with project-abc-build-142 and move them into the prod repository. 

Alternatively, if the build fails testing, then you can issue the call to delete all components tagged with project-abc-build-142.

REST Endpoints

See REST and Integration API for more details on using these endpoints via the interactive user interface.

Promotion

POST service/rest/v1/staging/move/{repository}

This endpoint promotes (or moves) components that match a search into the specified repository.

curl -u admin:admin123 -X POST 'http://127.0.0.1:8081/service/rest/v1/staging/move/uat?tag=project-abc-142'

This example moves all components tagged with project-abc-142 into the repository uat. Note that you can use any search criteria, but the tag parameter is most common when staging. See Search API for more information.

The response will include a payload showing the moved components.

{
    "status": 200,
    "message": "Move Successful",
    "data": {
        "destination": "uat",
        "components moved": [
            {
                "name": "project-abc",
                "group": "com.mycompany",
                "version": "2.1.1"
            }
        ]
    }
}

Deletion

POST /service/rest/v1/staging/delete

This endpoint deletes components that match a search from a repository. The primary use case when staging is to delete a set of components that failed testing. 

curl -u admin:admin123 -X POST 'http://127.0.0.1:8081/service/rest/v1/staging/delete?tag=project-abc-142'

This example removes all components with the tag project-abc-142. As with Promote, you can use any search criteria, but the tag parameter is most common when staging. See Search API for more information.

The response will include a payload showing the deleted components.

{
    "status": 200,
    "message": "Delete Successful",
    "data": {
        "components deleted": [
            {
                "repository": "uat",
                "group": "com.mycompany",
                "name": "project-abc",
                "version": "2.1.1"
            }
        ]
    }
}

Integrations

The Sonatype Nexus Platform Plugin for Jenkins includes staging-related build steps to help you implement staging workflows in your builds.

Nexus Repository 2 Migration

We do not support migration from Nexus Repository 2 staging to Nexus Repository 3 staging. We have completely redesigned the staging feature set in Nexus Repository 3, and it is not compatible with Nexus Repository 2 staging.  We redesigned staging to provide a set of flexible building block capabilities that you can combine and orchestrate as needed to accomodate your organization's software build and release pipeline. You can easily integrate these capabilities into CI/CD systems using REST endpoints.

See our guide for more details about Nexus Repository 2 and 3 staging differences.

Limitations

  • Only supports hosted repositories
  • Only supports Apt, Docker, Maven, npm, NuGet, PyPI, Raw, and Yum formats
  • You can only transfer between repositories of the same policy; you cannot transfer from a snapshot repository to a release repository