Repository Management with Nexus

11.2. Configuring the Nexus Staging Suite

11.2.1. Overview

The Staging Suite is part of the default Nexus Professional install and is accessible with the menu items Staging Profiles, Staging Repositories, Staging Ruleset, and Staging Upload options in the left-hand navigation menu of the Nexus interface called Build Promotion.

Staging Profiles define the rules by which artifact deployments from your project are intercepted by Nexus and staged in Staging Repositories.

Staging Repositories are dynamically created by Nexus as they are needed. They are temporary holding repositories for your artifacts that are used for the different staging related steps. Using them in the Nexus user interface users can promote the contents of the staging repository to a hosted repository, discard them and more.

Staging Rulesets allow you to define rules that the artifacts being deployed have to follow in order to allow successful deployment.

Staging Upload allows you to manually upload artifacts to Nexus via the user interface rather than by using your build system.

11.2.2. Configuring a Staging Profile

Staging profiles control the process by which artifacts are selected for staging. When you define a Staging profile, you are defining a set of rules which will control the way in which Nexus intercepts an artifact deployment and what actions to perform during and after staging the artifacts. When you click on Staging Profiles in the Nexus menu, you will see a list of configured staging profiles. This list allows you to Add… and Delete staging profiles. Click on an existing staging profile in the list and the panel below the list will display the configuration of the profile.

The list of staging profiles displayed also determines the order in which the profiles are examined when a component is deployed to staging. Going down the list each profile is checked for a match of the deployed component characteristics to the configuration of the profile. If a match is found a staging repository for this profile with the deployed components is created. Otherwise the next profile in the list is examined. Specifically with implicit matching criteria being used for your deployments as explained in more detail below, this order becomes important and can be controlled by selecting a staging profile and using the Move Up and Move Down buttons on the top of the list. Once you have created the desired order, press the Save Order button and confirm the order in the dialog.

Clicking on Add… will display the drop-down menu shown in Figure 11.4, “Adding a Staging Profile”.

figs/web/staging_add-staging-profile.png

Figure 11.4. Adding a Staging Profile


Selecting Staging Profile will create a new staging profile and display the form shown in Figure 11.5, “Creating a New Staging Profile”.

Figure 11.5, “Creating a New Staging Profile” defines a staging profile named "Test". It is configured to only intercept explicit deployments in the Profile Selection Strategy using the Profile ID and the Nexus Staging Maven Plugin. It uses the template Maven2 (hosted, release) for newly created temporary staging repositories, and it will automatically add closed staging repositories to the Public Repositories group. In addition it is configured to verify the deployment against the rules defined in Sonatype CLM for the CLM Application Id "bom1-12345678"

figs/web/staging-profile-edit.png

Figure 11.5. Creating a New Staging Profile


The form allows you to configure a profile with the following fields:

Profile ID and Deploy URL
These two fields are only available as read only display once a profile has been created. The Profile ID displays the unique identifier that can be used for staging to this repository using the Nexus Staging Maven Plugin. The Deploy URL displays the generic staging URL that can be used with the default Maven Deploy Plugin together with the Repository Target configuration to intercept the deployment and move the artifacts into the Staging Suite instead.
Profile Name
The name of the staging profile. This can be an arbitrary value. It is simply a convenience for the Nexus Administrator, and it is also used to create Nexus roles that are used to grant permissions to view and manipulate staging repositories created by this profile.
Profile Selection Strategy

Select the strategy used by Nexus to select this staging profile. Explicit or Implicit is the default behavior and causes Nexus to select the profile by the provided staging profile identifier and if none is provided fall back to an automatic determination. It is necessary to be used with the Maven Deploy Plugin and the correct staging profile is determined using Repository Targets together with the generic Deploy URL of Nexus.

When using the Nexus Staging Maven Plugin for deployments, and therefore an explicitly defined staging profile in the project POM, the setting should be changed to Explicit Only. This will prevent the profile from implicitly capturing a deployment in this repository due to the matching defined and allow Nexus to ensure that the deployment reaches the Staging Profile with the configured Staging Profile ID even if the default matching and staging profile order could potentially cause a deployment to end up in a different profile.

Searchable Repositories
The default value of enabling this feature will cause any new artifacts in this staging profile to be added to the indexes and therefore be available in search queries. Disable this feature to "hide" artifacts in staging.
Staging Mode
This field contains the options "Deploy," "UI Upload," and "Deploy and UI Upload." This controls how artifacts can be staged to this staging profile. If Deploy is selected, artifacts can only be deployed using Maven to upload build artifacts. If UI Upload is selected, users can upload artifacts to Nexus using the Nexus user interface.
Template
Defines the template for the format of the temporary staging repositories created by this staging profile. The current version of Nexus Professional provides the option "Maven2 (hosted, release)" only. Additional templates can be supplied by plugins that enable staging for other repository types. An example for such a plugin is the Nexus Yum Plugin.
Repository Target
When a developer deploys an artifact to the generic Deploy URL, the Staging Suite will check to see if the artifact matches the patterns defined in this Repository Target. The repository target defines the "trigger" for the creation of a staging repository from this staging profile and is only needed for implicit deployments with the Deploy URL and not for explicit deployments using the Profile ID.
Release Repository
Staged artifacts are stored in a temporary staging repository which is made available via Target Groups. Once a staged deployment has been successfully tested, artifacts contained in the temporary staging repository are promoted to a hosted repository as their final storage place. The Release Repository setting configures this target release repository for this staging profile.
CLM Applicaiton Id
Configures the application identifier defined in the Sonatype CLM server, allowing you to use the rules defined there for staging within Nexus. More details can be found in Section 11.6, “Policy Enforcement with Sonatype CLM”.
Content Type
Nexus can create staging repositories for repositories of type Maven2. This value is automatically selected based on the chosen template.
Target Groups
When a Staging Repository is "closed" and is made available to users and developers involved in the testing process, the temporary Staging Repository is added to one or more Repository Groups. This field defines those groups. It is a best practice to create a separate group, different from the group typically used for development like the default Public Repositories group for staging. This prevents the staged artifacts from leaking to all users and allows you to control access to the them via security settings for the separate repository group. In many cases mulitple target groups can be useful for different user groups to have access.
Close Repository Notification Settings
After a developer has deployed a set of related release artifacts, a staging repository is "closed". This means that no further artifacts can be deployed to the same staging repository. A repository would be closed when a developer is satisfied that a collection of staged artifacts is ready to be certified by a manager or a quality assurance resource. In this setting, it is possible to define email addresses and roles which should be notified of a staging repository being closed. A notification email will be sent to all specified email addresses, as well as all Nexus users in the specified roles, informing that a staging repository has been closed. It is also possible to select that the creator of the staging repository receives this notification.
Promote Repository Notification Settings
Once a closed staging repository has been certified by whoever is responsible for testing and checking a staged release, it can then be promoted (published) or dropped (discarded). In this setting, it is possible to define email addresses and Nexus security roles which should be notified of a staging repository being promoted. A notification email will be sent to all specified email addresses, as well as all Nexus users in the specified roles, informing that a staging repository has been promoted. It is also possible to select that the creator of the staging repository receives this notification.
Drop Repository Notification Settings
In this setting, it is possible define email addresses and roles which should be notified of a staging repository being dropped. A notification email will be sent to all specified email addresses, as well as all Nexus users in the specified roles, informing that a staging repository has been dropped. It is also possible to select that the creator of the staging repository receives this notification.
Close Repository Staging Rulesets
This defines the rulesets which will be applied to a staging repository before it can be closed. If the staging repository does not pass the rules defined in the specified rulesets, you will be unable to close it. For more information about rulesets, see Section 11.5, “Enforcing Standards for Deployment and Promotion with Rulesets”.
Promote Repository Staging Rulesets
This defines the rulesets which will be applied to a staging repository on promotion. If the staging repository does not pass the rules defined in the specified rulesets, the promotion will fail with an error message supplied by the failing rule. For more information about rulesets, see Section 11.5, “Enforcing Standards for Deployment and Promotion with Rulesets”.

11.2.3. Configuring Build Promotion Profiles

A Build Promotion profile is used when you need to add an additional step between initial staging and final release. To add a new Build Promotion profile, open the Staging Profiles link from the Nexus menu and click on Add… to display the drop-down menu shown in Figure 11.6, “Multilevel Staging and Build Promotion”. Select Build Promotion Profile from this drop-down to create a new Build Promotion Profile.

figs/web/staging-build-promotion-profile-add.png

Figure 11.6. Multilevel Staging and Build Promotion


After creating a new Build Promotion profile, you will see the form shown in Figure 11.7, “Configuring a Build Promotion Profile”. This form contains the following configuration fields:

Profile Name
This is the name for the Build Promotion profile which will be displayed in the promotion dialog and be associated with repositories created from this promotion profile.
Template
This is the template for repositories generated by this Build Promotion profile. The default value for this field is "Maven2 (group)".
Target Groups
This is the most important configuration field for a Build Promotion profile. It controls the group that promoted artifacts will be made available through. Artifacts can be made available through one or more groups.
figs/web/staging_closed-beta-promotion-group.png

Figure 11.7. Configuring a Build Promotion Profile


11.2.4. Staging Related Security Setup

Staging Suite is controlled by three roles:

  • Staging: Deployer
  • Staging: Promoter
  • Staging: Repositories

These roles are available as general admin roles that apply to all staging profiles with the respective access. When you create a new staging profile, Nexus will create new roles that grant permissions specific to that staging profile. If you created the staging profile named Test, Nexus created the three new and profile specific roles:

Staging: Repositories (Test)
This role grants a user read and view access to the staging repositories created by the Test staging profile.
Staging: Deployer (Test)
This role grants all of the privileges from the Staging: Repositories role and in addition grants the user permission to deploy artifacts, close and drop any staging repository created by the Test staging profile.
Staging: Promoter (Test)
This role grants the user to right to promote staging repositories created by the Test staging profile.

To perform a staged deployment, the user deploying the artifact must have the "Staging: Deployer (admin)" role or the "Staging: Deployer" role for a specific Staging Profile.

To configure the deployment user with the appropriate staging role, click on Users under the Security menu in the Nexus menu. Once you see the Users panel , click on the deployment user to edit this user’s roles. Click on the Add button in the Role Management section of the Config tab visible in Figure 11.8, “Adding a Role to a User” for the user to be able to add new roles to the user.

figs/web/staging-user-add-role.png

Figure 11.8. Adding a Role to a User


Use the Filter section with the keyword Staging and press the Apply Filter button to see all available staging related roles as displayed in Figure 11.8, “Adding a Role to a User”.

figs/web/staging-user-add-role-dialog.png

Figure 11.9. Available Roles for Staging with a Test Staging Profile


You should see the "Staging: Deployer (admin)" role listed as well as the Test staging profile specific role, the promoter and repositories ones for admin and Test and a few staging user interface related roles. These roles are required if interaction with the staging suite in the Nexus user interface is desired and allow you to control the details about this access. If you need to add a specific permission to activate a single Staging Profile, you would select that specific role.

Once the deployment user has the "Staging: Deployer (admin)" role, you can then use this user to deploy to the staging URL and trigger any staging profile. Without this permission, the deployment user would not be able to publish a staged artifact.

In a similar fashion you can assign the promoter role to users.

In addition to the roles created a number of specific privileges is available to further customize the access to the staging suite:

Staging Profiles
allows control of create, read, delete and update operations on staging propfiles.
Staging Repository: test-001
separate privileges for each staging repository allowing create, read, update and delete operations are generated automatically.
Staging: All Profiles, Owner All Profiles and Profile xyz
these staging profile specific priviliges can be granted for drop, promote, read and finish operations.
Staging: Rule Set and Staging: Rule Types
control access to staging rules and rule types
Staging: Upload
controls access to the manual staging upload user interface
Staging: Repositories, Promote Repository, Profile Ordering, Close Staging and others
a number of application user interface specific privileges allow fine grained control over access in the user interface

11.2.5. Using Repository Targets for Staging

The Staging Suite intercepts deployments to Nexus using Repository Targets as documented in Section 6.14, “Managing Repository Targets” when using implicit matching as a profile selection strategy based on the artifacts path in the repository.

For example, if you wanted to intercept all deployments to the com.sonatype.sample groupId, you would create a repository target with a pattern with a regular expression of ^/com/sonatype/sample/.* and use that repository target in your Staging Profile configuration.