Configuring the Staging Suite

Overview

The Staging Suite is part of the default Nexus Repository Manager Pro 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 user interface called Build Promotion. 

Staging Profiles define the rules by which component deployments from your project are intercepted by the repository manager and staged in Staging Repositories. 

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

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

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

Configuring a Staging Profile

Staging Profiles control the process by which components are selected for staging. When you define a profile, you are defining a set of rules which will control the way in that the repository manager intercepts a component deployment and what actions to perform during and after staging the components. When you click on Staging Profiles in the main 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”.

Figure 11.4. Adding a Staging Profile

Selecting Staging Profiles 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 Nexus IQ Server for the CLM Application Id bom1-12345678.

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 displayed as "read only" 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 components 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 Administrator, and it is also used to create 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 the repository manager to select this staging profile. Explicit or Implicit is the default behavior and causes the repository manager to select the profile by the provided staging profile identifier and to fall back to an automatic determination, if none is provided. 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.

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 the repository manager 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 components in this staging profile to be added to the indexes and therefore be available in search queries. Disable this feature to "hide" components in staging.

Staging Mode

This field contains the options Deploy, UI Upload, and Deploy and UI Upload. This controls how components can be staged to this staging profile. If Deploy is selected, components can only be deployed using Maven to upload build components. If UI Upload is selected, users can upload components using the user interface.

Template

Defines the template for the format of the temporary staging repositories created by this staging profile. The current version of Nexus Repository Manager Pro 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 a component to the generic Deploy URL, the Staging Suite will check to see if the component 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 components are stored in a temporary staging repository that is made available via Target Groups. Once a staged deployment has been successfully tested, components 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 Application Id

Configure the application identifier defined in the Nexus IQ Server to allow to use of the rules defined there for staging. More details can be found in Section 11.6, “Policy Enforcement with Nexus IQ Server”.

Content Type

The repository manager 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 components from leaking to all users and allows you to control access to them via security settings for the separate repository group. In many cases multiple 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 components, a staging repository is closed . This means that no further components can be deployed to the same staging repository. A repository would be closed when a developer is satisfied that a collection of staged components 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 that should be notified of a staging repository being closed. A notification email will be sent to all specified email addresses, as well as all users in the specified roles, informing them 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 whomever 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 the email addresses and security roles that should be
notified of a staging repository being promoted. A notification email will be sent to all specified email addresses, as well as all users in the specified roles, informing them 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 to define email addresses and roles notified when a staging repository is being dropped. A notification email will be sent to all specified email addresses, as well as all users in the specified roles, informing them 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 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 Enforcing Standards for Deployment and Promotion with Rulesets.

Promote Repository Staging Rulesets

This defines the rulesets 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 Enforcing Standards for Deployment and Promotion with Rulesets.

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 main 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:

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

The name for the build promotion profile displayed in the promotion dialog and associated with repositories created from this promotion profile.

Template

The template for repositories generated by this build promotion profile. The default value for this field is Maven2 (group).

Target Groups

The Target Groups field is the most important configuration field for a build promotion profile, as it controls the group through which promoted components are made available. Components can be made available through one or more groups.

Figure 11.7. Configuring a Build Promotion Profile

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, the repository manager will create new roles that grant permissions specific to that staging profile. If you created the staging profile named Test, the repository manager 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 components, 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 component 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 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.

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

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

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

Staging Repository: test-001

There are 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-privileges 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.

Using Repository Targets for Staging

The Staging Suite intercepts deployments using Repository Targets as documented in Managing Repository Targets when using implicit matching as a profile selection strategy, based on the components 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.