Repository Management with Nexus

11.4. Managing Staging Repositories in Nexus

With a staging profile configured and a deployment completed as outlined in Section 11.2, “Configuring the Nexus Staging Suite” and Section 11.3, “Configuring your Project for Deployment”, you will have an automatically generated Staging Repository. All list of all staging repositories can be accessed by selecting the Staging Repositories item in the Build Promotion menu and is displayed in Figure 11.11, “Staging Repositories List Panel”


Figure 11.11. Staging Repositories List Panel

The header of this view provides buttons to Close, Promote, Release or Drop the staging repository currently selected in the list below. The Refresh button can be used to force a reload of repositories. The Filter by profile drop-down allows you to select one or multiple staging profiles, from which the repositories in the list were created. The list of repositories itself displays a number of columns with details for each repository. Further columns can be added by pressing on the drop-down triangle beside the currently selected column. Sorting by a single column in Ascending or Descending order can be set from the same drop-down as the column addition.


When triggering a transition for a staging repository from e.g., the open state to a the closed state a background task performs all the necessary operations. Since these are potentially longer running the user interface is not immediately updated and displays a in progress icon. You are required to press Refresh to get the latest state of all repositories.

By default the following columns are displayed:

a checkbox to allow operations on multiple repositories
Status Icon
an icon symbolizing the status of the staging repository
the name of the staging repository
the name of the staging profile, that was used to create the staging repository
status of the repository
date and time of the last update
textual description of the repository

Additional columns are:

Release To
target repository for the components in the staging repository after release
Promoted To
the build promotion profile, to which a staging repository was optionally promoted to
the username of the creator of the staging repository
date and time of the creation of the staging repository
User Agent
user agent string sent by the tool used for the deployment e.g., Apache-Maven/3.0.5…

You can also access staging repositories in the list of repositories available in the Repositories panel available via the Views/Repositories as a Nexus managed repository.

In the following sections, you will walk through the process of managing staging repositories. Once you have deployed a set of related components, you must close the repository moving it from an Open to a Closed state unless the deployment tool automatically closed the staging repository.

A repository in the Closed state, is added to a Repository Group and is made available for testing purposes or other inspection and can no longer received additional components in it.

When the component examination is complete, you can either Promote, Release or Drop the closed repository.

If the repository is dropped, the repository is discarded and removed from the Repository Group and the components are move to the Trash.

If the repository is promoted, it is assigned to a build promotion profile for further staging activities.

If the repository is released, its components are moved to the targe repository configured in the staging profile.


A scheduled task documented in Section 6.5, “Managing Scheduled Tasks” can be used to clean up inactive staging repositories automatically.

Selecting a staging repository in the list displays further details about the repository in the Summary, Activity and Content tabs below the list. An example for an open repository is displayed in Figure 11.12, “List of Activities Performed on a Promoted Staging Repository”.


Figure 11.12. List of Activities Performed on a Promoted Staging Repository

The Summary tab displays a number of properties of the staging repository and allows you to edit the Description. The properties include the name of the repository, creation and update time and date stamps, an activity indicator, the owner and originating IP number of the deployment as well as the user agent string sent by the deployment. All staging operations have a default description that is used if the input field is left blank.

The Activity tab shows all the activties that occured on a specific staging repository. An example for a promoted repository is displayed in Figure 11.13, “Details of an Open Staging Repository as Displayed under the List of Staging Repositories”. The activities are separated per activity and list all events that occured in an acivity. Selecting an event displays further details about the event on the right side of the tab.


Figure 11.13. Details of an Open Staging Repository as Displayed under the List of Staging Repositories

The Content tab displays a repository browser view of the staging repository content and allows you to filter and display the components in the tree view. Selecting a specific component triggers the display of further panels with further information about the component, in the same manner as other repository browser views. The tabs include Maven and Artifact information and others.

A Members tab is additionally shown for build promotion profile. It displays the source repositories and build promotion profiles from which this current build promotion profile was created.

11.4.1. Closing an Open Repository

Once you deploy a component that triggers a staging profile, Nexus Staging Suite will create a repository that contains the components you deployed. A separate staging repository is created for every combination of User ID, IP Address, and User Agent. This means that you can perform more than one deployment to a single Staging Repository as long as you perform the deployment from the same IP, with the same deployment user, and the same installation of Maven.

You can perform multiple deployments to an open staging repository. Depending on the deployment tool and your configuration the staging repository might be automatically closed during deployment or left open until manually closed.

Once you are ready to start testing the staging repository content, you will need to transition the repository from the open state to the closed state. This will close the staging repository to more deployments.

To close a repository, select the open staging repository in the list and by clicking the checkbox in the list or anywhere else in the row. For a open repository the Close and the Drop buttons above the table will be activated. Pressing the Close button will bring up the dialog for a staging deployer to describe the contents of the staging repository and confirm . This description field can be used to pass essential information to the person that needs to test a deployment.

In Figure 11.14, “Confirmation and Description Dialog for Closing a Staging Repository”, the description field is used to describe the release for the user that needs to certify and promote a release.


Figure 11.14. Confirmation and Description Dialog for Closing a Staging Repository

Confirming this state transition will close the repository and add the repository to the repository groups configured in the staging profile. The updated status will be visible in the list of staging repositories after a Refresh, since the transition could take longer depending on the configured staging rules and potential validation against Sonatype CLM.

11.4.2. Using the Staging Repository

Once the staging repository has been closed, it will automatically be added to the repository group(s) that are specified as target groups in the staging profile configuration.

This has the effect of making the staged artifacts available to everyone who is referencing this group. Developers who are referencing this repository group can now test and interact with the staged artifacts as if they were published to a Hosted repository.

While the artifacts are made available in a repository group, the fact that they are held in a temporary staging directory gives the staging user the option of promoting this set of artifacts to a hosted repository. Or alternatively the user can drop this temporary staging repository, if there are problems discovered during the testing and certification process for a release.

Once a staging repository is closed, you can also browse and search the repository in the staging repositories list.

Alternatively to view all staging repositories, click on the Repositories item in the Views/Repositories menu and then select Nexus Managed Repositories as shown in Figure 11.15, “Viewing Nexus Managed Repositories”.


Figure 11.15. Viewing Nexus Managed Repositories

This list allows you to access all Nexus Managed Repositories, just like the User Managed Repositories including browsing the content and accessing detailed information about the components in the repository. In addition to staging repositories, the list included procured repositories as documented in Chapter 10, Nexus Procurement Suite.

11.4.3. Releasing a Staging Repository

When you are finished testing or certifying the contents of a staging repository, you are ready to either release, promote or drop the staging repository. Dropping the staging repository will delete the temporary it from Nexus and remove any reference to this repository from the groups it was associated with. Releasing the staging repository allows you to publish the contents of this temporary repository to a hosted repository. Promoting the repository will move it to a build promotion profile.

You can release a staging repository by pressing Release , after selecting a closed staging repository from the staging repositories list. The Release Confirmation dialog displayed in Figure 11.16, “Confirmation Dialog for Releasing a Staging Repository” will allow you to supply a description and configure if the staging repository should be automatically dropped after the components have been released to the hosted repository.


Figure 11.16. Confirmation Dialog for Releasing a Staging Repository

11.4.4. Promoting a Staging Repository

If you have a closed staging repository that you want to promote to a Build Promotion Profile, open the list of Staging Repositories and click the Promote button to bring up the Promote Confirmation dialog displaed in Figure 11.16, “Confirmation Dialog for Releasing a Staging Repository”. It allows you to select the build promotion profile to which you want to stage the repository to as well as provide a description.


Figure 11.17. Confirmation Dialog for Promoting a Staging Repository

Clicking on the Promote button in the dialog will promote the staging repository to a build promotion repository and expose the contents of the selected staging repository through the target group(s) associated with the build promotion profile.

The build promotion repository is accessible in the staging repository list as displayed in Figure 11.18, “A Build Promotion Repository and its Members Panel”. If you add the column Promoted To to the list you will observe that Nexus keeps track of the promtion source. The Members tab for a build promotion repository displays the path of a build promotion repository back to a staging repository. One or more staging repositories can be promoted to a single build promotion profile.


Figure 11.18. A Build Promotion Repository and its Members Panel

11.4.5. Releasing, Promoting, and Dropping Build Promotion Profiles

When you configure a build promotion profile and promote staging repositories to promotion profiles, each build promotion profile creates a repository which contains one or more staging repositories. Just like you can promote the contents of a staging repository to a build promotion profile, you can also promote the contents of a build promotion profile to another build promotion profile. When you do this you can create hierarchies of staging repositories and build promotion profiles which can then be dropped or released together.


Figure 11.19. Releasing, Promoting, and Dropping Build Promotion Profiles

When you promote a staging repository to a build promotion profile, you make the contents of a staging repository available via a repository group associated with a build promotion profile.

For example, if you staged a few artifacts to a QA staging repository and then subsequently promoted that repository to a Closed Beta build promotion group, the contents of the QA staging repository would initially be made available via a QA repository group. After a build promotion, these artifacts would also be available via a Closed Beta repository group.

You can take it one step further and promote the contents of the Closed Beta Build Promotion profile to yet another build promotion profile. In this way you can have an arbitrary number of intermediate steps between the initial staging deployment and the final release.

If you drop the contents of a build promotion profile, you roll back to the previous state. For example, if you decided to drop the contents of the Closed Beta build promotion group, Nexus will revert the status of the staging repository from promoted to closed, and make the artifacts available via the QA staging repository. The effects of promoting, dropping, and releasing artifacts through a series of Staging Profiles and Build Promotion Profiles is shown in Figure 11.19, “Releasing, Promoting, and Dropping Build Promotion Profiles”.

When you perform a release on a build promotion profile, it rolls up to release all its members ultimately reaching a staging repository. Each staging repository is releases its components to the release repository configured in Figure 11.5, “Creating a New Staging Profile”. Because a build repository can contain one or more promoted staging repositories, this means that releasing a build promotion profile can cause components to be published to more than one release repository.


Figure 11.20. Promoting Multiple Repositories to the Same Build Promotion Profile

Build promotion profiles are not directly related to release repositories, only staging profiles are directly associated with target release repositories. Figure 11.20, “Promoting Multiple Repositories to the Same Build Promotion Profile” illustrates this behavior with two independent staging repositories each configured with a separate release repository. Releasing the build promotion profile causes Nexus to publish each staging repository to a separate hosted repository.

11.4.6. Multilevel Staging and Build Promotion

Nexus also supports multilevel staging and build promotion. With multilevel staging, a staging repository can be tested and then promoted to multiple separate build promotion profiles consecutively and exposed through different repository groups to allow for additional testing and qualification before a final frelease. Figure 11.21, “Multilevel Staging and Build Promotion” illustrates a potential use for multilevel staging:

A developer publishes components to a QA staging profile which exposes the staged components in a QA repository group used by an internal quality assurance team for testing.
Promote to Beta
Once the QA team has successfully completed testing, they promote the temporary staging repository to a build promotion profile which will expose the staged components to a limited set of customers who have agreed to act as a beta testers for a new feature.
Once this closed beta testing period is finished, the staged repository is then released and the artifacts it contains are published to a hosted release repository and exposed via the public repository group.

Figure 11.21. Multilevel Staging and Build Promotion

To support this multilevel staging feature, you can configure Build Promotion profiles as detailed in Section 11.2.3, “Configuring Build Promotion Profiles”. Once you have promoted a Staging Repository to a Build Promotion profile, you can drop, promote, or release the artifacts it contains as detailed in Section 11.2, “Configuring the Nexus Staging Suite”.