Staging

Available in Nexus Repository Manager Pro only

Overview

In modern software development, it is imperative to thoroughly test software before it is deployed to a production system or externally accessible repository. Mostly commonly a release candidate will first be deployed to a staging system which is a close copy of the production system so it can undergo a series of rigorous tests before a decision is made to promote it to production or return it to development.

The staging functionality in Nexus Repository Manager Pro supports promotion of software components matching your organization's software development life cycle phases by moving those components between repositories. This allows the creation of isolated release candidates that can be discarded or promoted to make it possible to support the decisions that go into certifying a release.

Building Blocks

The basic building blocks of the staging functionality consist of hosted repositories, component tags, and the ability to move and delete components between those hosted repositories directly via a REST API. The following briefly describes each of these building blocks:

  • Hosted repositories - Components/assets are uploaded to hosted repositories and can then be promoted/moved to other hosted repositories or deleted.
  • Component tags - Uploaded components/assets are tagged so that they can be identified as a logical group and be transferred together. See Tagging for more information.
  • REST endpoints
    • Move - allows all components and assets matching a specified search query to be moved to a target repository.
    • Delete - allows for the deletion of all components and assets matching a specified search query.

There are some usage limitations to the current staging functionality which should be reviewed prior to use in your workflows.

Workflow

As depicted in the figure below, Typical Staging Workflow, a typical staging workflow will involve some hosted repositories (along with possibly some group repositories to include other dependencies) and an external system which is coordinating the promotion process. This usually includes a CI system, such as Jenkins, which will continuously build each commit, as well as a release manager who will promote some builds for testing and ultimately release.

Build Phase

When a developer pushes new code, the CI system will pick it up and perform the build automatically including any unit or integration tests. The resulting artifacts are then uploaded to the incoming NXRM repository. As part of this operation the artifacts will be tagged so they can later be identified. Commonly the CI project/job ID and the build ID can be used as the tag. For example, the job project-abc with the build ID 142 would result in the tag project-abc-build-142.

Test Phase

When the release manager decides, any given build can be promoted to the next stage. As shown in the figure below, a build would be promoted from the incoming hosted repository to the uat repository in preparation for testing. This could be initiated via a button in the CI job/pipeline or perhaps a separate job. NXRM will receive the promotion call to take all components tagged with project-abc-build-142 and move them into the uat repository. This repository is available to the testing group of users so that they can ensure quality.

Release Phase

When testing is complete, the build can then be promoted to the next stage which in our example is production. As shown in the figure below, a build would be promoted from the uat repository to the prod repository in preparation for release. This again may be initiated via button in the CI job/pipeline or a separate job. NXRM will receive the promotion call to take all components tagged with project-abc-build-142 and move them into the prod repository.

If the build fails testing, then the release manager can instead issue the call to delete all components tagged with project-abc-build-142.

simple-staging-workflow

REST Endpoints

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

Promotion

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

This endpoint allows us to promote (or move) 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 will move all components tagged with project-abc-142 into the repository uat. Note that any search criteria can be used though within the context of staging the tag parameter is most common. See Search API for more.

The response will include a payload that shows the components that were moved.

{
    "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 allows us to delete components that match a search from a repository. The primary use case within the context of staging is if a set of components has been promoted to a test environment, and then failed testing, it can be deleted from the system.

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

This will remove all the components with the tag project-abc-142. As with Promote, any search criteria can be used though within the context of staging the tag parameter is most common. See Search API for more.

The response will include a payload that shows the components that were deleted.

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

NXRM 2 Migration

Migration from NXRM 2 staging to NXRM 3 staging is not supported. The staging feature set in NXRM 3 has been compeletely redesigned and is not compatible with NXRM 2 staging.  The rationale behind this redesign was to provide a set of flexible building block capabilities that can be combined and orchestrated as needed to accomodate 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 while not being prescriptive of the workflows or client tooling and technologies needed to interact with them.

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

Limitations

  • Only hosted repositories are supported.
  • Only Maven, Raw, NPM, Docker, Yum, NuGet and APT formats are currently supported.
  • You can only transfer between repositories of the same policy.  You cannot transfer from a snapshot repository to a release repository.