Staging

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

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 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 under your delivery or code promotion process.

Other features of staging in Nexus Repository 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

• REST Endpoints

Used to move and delete components between hosted repositories.

Limitations

Staging has the following limitations:

• Staging is supported with the following hosted repositories:

Apt, Docker, Helm, Maven, npm, NuGet, PyPI, Raw, Yum

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

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

• For Docker repositories, staging move operations copy image layers to the destination repository but do not remove layers from the source repository. This is because Docker layers can be shared across multiple images, and the Docker - Delete unused manifests and images task does not remove layers that exist in any other repository. As a result, disk usage in the source repository will not decrease after a move operation. Staging move is not an effective approach for cleaning up Docker repositories.

Note

To reclaim disk space in Docker repositories, apply a cleanup policy directly to the source repository instead of using staging move operations.

• To perform a staging move, a user needs the following privileges:

Source Repository

nx-repository-view-<repo-format>-<repoId>-delete

Destination Repository

nx-repository-view-<repo-format>-<repoId>-add

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.

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

Move

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"\
            }\
        ]
    }
}

Delete

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"\
            }\
        ]
    }
}