Skip to main content

Staging

Note

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

Overview

In modern software development, it is imperative to thoroughly test the software before deploying it to a production system or externally accessible repository. Most 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.

Staging allows your organization to have some sequence of hosted repositories and move or promote components through those repositories in accordance with your delivery or code promotion process. Other features of staging in Nexus Repository Pro let you do the following:

  • 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.

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.

Warning

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

Limitations

Staging has the following limitations:

  • Staging can only be used with hosted repositories in Apt, Docker, Maven, npm, NuGet, PyPI, Raw, and Yum formats.

  • You can only transfer between repositories of the same version policy; you cannot transfer from a snapshot repository to a release repository.

  • Staging moves are not supported for hosted repositories that are configured as the writable member for a Docker group repository; attempting a move for a repository that is a writable member of a Docker group repository will result in an error.

    • This limitation exists due to the way Docker image deployments work. Docker images are comprised of a tag, manifest(s), and layers (See Components and Assets in Docker). When using Docker group deployments, manifests and layers that already exist in any member of the group repository will not be uploaded to the target hosted repository. This happens because Docker clients always test to see if a file is present in the remote before uploading it. This makes it highly likely that some of the uploaded image files will be present in proxy repositories within the group or in other repositories that were not included in the tagging command. Attempting a staging move on an image that has either of these problems will result in a failure.

    • See the Pushing Images to a Group Repositoryfor more information on writable repositories.

  • In order to perform a staging move, a user needs the following privileges:

    nx-repository-view-<repo-format>-<repoId>-delete privilege in the source repository

    nx-repository-view-<repo-format>-<repoId>-add privilege in the destination repository

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.

14156058.png

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 Sonatype Nexus Repository 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. Sonatype Nexus Repository 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.

The response will include a payload showing the moved components.

Example Response

{
    "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.

The response will include a payload showing the deleted components.

Example Response

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

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 accommodate your organization's software build and release pipeline. You can easily integrate these capabilities into CI/CD systems using REST endpoints.

See the Upgrading Staging topic for more details about Nexus Repository 2 and 3 staging differences.