Repository Management with Nexus
10.4. Managing Staging Repositories in Nexus
With a staging profile configured and a deployment completed as
outlined in Section 10.2, “Configuring the Nexus Staging Suite” and
Section 10.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 10.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.
- NOTE
-
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
Refreshto get the latest state of all repositories.
By default the following columns are displayed:
- Checkbox
- a checkbox to allow operations on multiple repositories
- Status Icon
- an icon symbolizing the status of the staging repository
- Repository
- the name of the staging repository
- Profile
- the name of the staging profile, that was used to create the staging repository
- Status
- status of the repository
- Updated
- date and time of the last update
- Description
- 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
- Owner
- the username of the creator of the staging repository
- Created
- 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…
Tip
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.
Note
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 10.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 10.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 10.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.
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 10.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.
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.
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 10.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 9, Nexus Procurement Suite.
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 10.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.
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 10.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.
![fig-staging-repository-promote-dialog]](figs/web/staging-repository-promote-dialog.png)
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 10.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.
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.
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 10.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 10.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.
Build promotion profiles are not directly related to release repositories, only staging profiles are directly associated with target release repositories. Figure 10.20, “Promoting Multiple Repositories to the Same Build Promotion Profile” illustrates this behaviour 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.
Nexus also supports multi-level staging and build promotion. With multi-level 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 10.21, “Multi-level Staging and Build Promotion” illustrates a potential use for multi-level staging:
- Stage
- 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.
- Release
- 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.
To support this multi-level staging feature, you can configure Build Promotion profiles as detailed in Section 10.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 10.2, “Configuring the Nexus Staging Suite”.