{inrmonly}
If you release software, you will often need to test a release before deploying it to a production system or an externally accessible repository. For example, if you are developing a large, enterprise web application, you may want to stage a release candidate to a staging system and perform a series of rigorous tests before a release manager makes a decision to either return a system to development or deploy a system to production.
The staging suite in {pro} allows an organization to create a temporary staging repository and to manage the promotion of components from a staging repository to a release repository. This ability to create an isolated, release candidate repository that can be discarded or promoted makes it possible to support the decisions that go into certifying a release, while the certification process is done on the same binaries that will ultimately be released.
Without the staging suite, when a developer deploys a component to a hosted repository such as the release repository, this component is published and immediately made available, having no oversight, no process and no certification process. There is no chance to test the component before writing the component to a hosted repository. If there is a mistake in the release, often the only option available is to republish the components to the release repository or deploy a new version of the components.
While this is acceptable for some users, organizations and enterprises with a QA cycle often need a temporary storage for potential release candidates: a staging repository. With the staging suite, an organization can automatically stage releases to a temporary repository that can then be used to test and certify a set of components, before they are published to a final release repository. This temporary repository can then be promoted as a whole or dropped, depending on the results of testing. When used, the binary components being tested and certified are the identical components that will ultimately be released. You will not have a clean fresh build kicked off after the certification finished, as is often the case without a staging suite being used.
Here’s how staging works in {pro}:
-
A developer deploys a component (or a set of components) to {pro}.
-
The staging suite intercepts this deployment and determines if the deployment matches for a staging profile.
-
If a match is found, a temporary staging repository is created and the components are deployed to this repository.
-
Once the developer has deployed a set of components, they will then "Close" the staging repository.
-
The Staging Suite will then add this temporary staging repository to one or more Target Repository Groups.
Once the staging repository is closed and has been added to a target repository group, the components in the staging repository are available to users for testing and certification via a repository group. Tests can be performed on the components as if they were already published in a hosted repository. At this point different actions can be performed with the staging repository:
- Release
-
A user can "release" a staging repository and select a hosted repository to which to publish components. Releasing the contents of a repository publishes all components from the staging repository to a hosted repository and deletes the temporary staging repository.
- Drop
-
A user can "drop" a staging repository. Dropping a staging repository will remove it from any groups and delete the temporary staging repository.
- Promote
-
If your repository manager contains Build Promotion profiles, you will also see an option to "promote" a staging repository to a Build Promotion Group. When you promote a staging repository you expose the contents of that staging repository via additional groups. Build Promotion profiles are explained in detail in the next section.
The Staging Suite is part of the default {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.
Staging profiles control the process by which components are selected for staging. When you define a Staging 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 Adding a Staging Profile.
Selecting 'Staging Profile' will create a new staging profile and display the form shown in Creating a New Staging Profile.
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 {iq} for the 'CLM Application Id' bom1-12345678.
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 {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 {iq} to allow to use of the rules defined there for staging. More details can be found in Policy Enforcement with {iq}.
- 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.
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 Multilevel Staging and Build Promotion. Select 'Build Promotion Profile' from this drop-down to create a new build promotion profile.
After creating a new build promotion profile, you will see the form shown in 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.
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 '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 Adding a Role to a User for the user to be able to add new roles to the 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 Adding a Role to a User.
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.
The Staging Suite intercepts deployments using Repository Targets as documented in [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.
Once the repository manager is configured to receive components in the staging suite as documented in Configuring the Staging Suite, you will have to update your project build configuration to deploy to the staging suite.
The preferred way to do this is to take advantage of the features provided by the Nexus Staging Maven plugin or the Nexus Staging Ant tasks as documented in Deployment with the Nexus Staging Maven Plugin and Deployment with the Nexus Staging Ant Tasks.
If you need to continue to use the Maven Deploy plugin, you can read about using it with the staging suite in Deployment with the Maven Deploy Plugin.
With all tools you can use the manual upload of your components documented in Manually Uploading a Staged Deployment.
The Nexus Staging Maven plugin is a specific and more powerful replacement for the Maven Deploy plugin with a number of features specifically geared towards usage with the staging suite. The simplest usage can be configured by adding it to the project build plugins section as an extension:
<build>
<plugins>
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.6</version>
<extensions>true</extensions>
<configuration>
<serverId>nexus</serverId>
<nexusUrl>http://localhost:8081/nexus/</nexusUrl>
</configuration>
</plugin>
|
Note
|
It is important to use a version of the plugin that is compatible with your {pro} server. Version 1.2 is compatible with {pro} 2.3, Version 1.4.4 is compatible with {pro} 2.4, Version 1.4.8 is compatible with {pro} 2.5 and 2.6. 1.5 and 1.6.x can be used for {pro} 2.7 to 2.10. The latest version of the plugin available is always compatible with the latest available version of {pro}. Try to use the newest possible plugin version to take advantage of any available improvements. |
Following Maven best practices, the version should be pulled out into a pluginManagement section in a company POM or parent POM.
This configuration works only in Maven 3 and automatically replaces the deploy goal invocation of the Maven Deploy plugin in the deploy Maven life cycle phase with the deploy goal invocation of the Nexus staging Maven plugin.
The minimal required configuration parameters for the Nexus Staging Maven plugin are:
- serverId
-
The id of the server element in settings.xml from which the user credentials for accessing the repository manager should be retrieved.
- nexusUrl
-
The base URL at which the repository managerto be used for staging is available.
With this configuration the Nexus Staging Maven plugin will stage the components locally and connect to the repository manager. It will try to determine the appropriate staging profile by matching the component path with any repository targets configured with staging profiles with an activated implicit profile selection strategy. If an appropriate staging profile is found, a staging repository is created on the fly and the components are deployed into it. If no profile is found, the upload will fail.
To successfully deploy to your repository manager, you will need to update your Maven Settings with the credentials for the deployment user. These credentials are stored in the Maven Settings file in ~/.m2/settings.xml.
To add these credentials, add the following element to the servers element in your ~/.m2/settings.xml file as shown in Listing deployment credentials in Maven Settings.
<settings>
...
<servers>
...
<server>
<id>nexus</id>
<username>deployment</username>
<password>deployment123</password>
</server>
</servers>
...
</settings>
Note that the server identifier listed in Listing deployment credentials in Maven Settings should match the serverId parameter you are passing to the Nexus Staging Maven plugin and in the example contains the default password for the deployment user - deployment123. You should change this password to match the deployment password for your repository manager.
If more control is desired over when the plugins deploy goal is activated or if Maven 2 is used, you have to explicitly deactivate the Maven Deploy plugin and replace the Maven Deploy plugin invocation with the Nexus Staging Maven plugin like visible in Usage of Nexus Staging Maven Plugin for Maven 2.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-deploy-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<executions>
<execution>
<id>default-deploy</id>
<phase>deploy</phase>
<goals>
<goal>deploy</goal>
</goals>
</execution>
</executions>
<configuration>
<serverId>nexus</serverId>
<nexusUrl>http://localhost:8081/nexus/</nexusUrl>
<!-- explicit matching using the staging profile id -->
<stagingProfileId>129341e09f2ee275</stagingProfileId>
</configuration>
</plugin>
...
The implicit matching relies on the setup of repository targets as well as the correct order of staging profiles and is therefore an error prone approach when many staging profiles are in use.
The preferred way to work in this sceneario is to change the profile selection strategy on all staging profiles to explicit only and pass the staging profile ID to the Nexus Staging Maven plugin using the stagingProfileId configuration parameter as documented above. A full example pom.xml for deployment of snapshot as well as release builds with the Nexus Staging Maven plugin using explicit matching for the staging profile and locally staged builds and atomic uploads is available in Full example pom.xml for Nexus Staging Maven Plugin usage.
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.sonatype.training.nxs301</groupId>
<artifactId>explicit-staging-example</artifactId>
<version>1.0.0</version>
<distributionManagement>
<snapshotRepository>
<id>nexus-snapshots</id>
<url>http://localhost:8081/nexus/content/repositories/snapshots</url>
</snapshotRepository>
</distributionManagement>
<build>
<plugins>
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.3</version>
<extensions>true</extensions>
<configuration>
<serverId>nexus-releases</serverId>
<nexusUrl>http://localhost:8081/nexus/</nexusUrl>
<!-- update this to the correct id! -->
<stagingProfileId>1296f79efe04a4d0</stagingProfileId>
</configuration>
</plugin>
</plugins>
</build>
</project>
In order to deploy project components with the above setup you would invoke a build with mvn clean deploy.
The build will locally stage the components for deployment in target/nexus-staging on the console and create a closed staging repository holding the build components. This execution of the deploy goal of the Nexus Staging Maven plugin performs the following actions:
-
Components are staged locally.
-
A staging profile is selected either implicitly or explicitly.
-
A staging repository is either created on the fly, if needed, or just selected.
-
An atomic upload to the staging repository is performed.
-
The staging repository is closed (or dropped if upload fails).
The log of a successful deployment would look similar to this:
[INFO] --- nexus-staging-maven-plugin:1.1.1:deploy (injected-nexus-deploy) @ staging-example ---
[INFO] Using server credentials with ID="nexus-releases" from Maven settings.
[INFO] Preparing staging against Nexus on URL http://localhost:8081/nexus/
[INFO] * Remote Nexus reported itself as version 2.2.1 and edition "Professional"
[INFO] * Using staging profile ID "12a1656609231352" (matched by Nexus).
[INFO] Staging locally (stagingDirectory=
"/Users/manfred/dev/explicit-staging-example/target/nexus-staging/12a1656609231352")...
Uploading: file: ... explicit-staging-example-1.0.0.jar
Uploaded: file: ... explicit-staging-example-1.0.0.jar (4 KB at 1051.1 KB/sec)
Uploading: file: ... explicit-staging-example-1.0.0.pom
Uploaded: file: ... explicit-staging-example-1.0.0.pom (4 KB at 656.2 KB/sec)
Downloading: file: ...maven-metadata.xml
Uploading: file: ...maven-metadata.xml
Uploaded: file: ... maven-metadata.xml (322 B at 157.2 KB/sec)
[INFO] Staging remotely...
[INFO] Uploading locally staged directory: 12a1656609231352
[INFO] Performing staging against Nexus on URL http://localhost:8081/nexus/
[INFO] * Remote Nexus reported itself as version 2.2.1 and edition "Professional"
[INFO] * Created staging repository with ID "test-002",
applied tags: {javaVersion=1.6.0_37, localUsername=manfred}
[INFO] * Uploading locally staged components to:
http://localhost:8081/nexus/service/local/staging/deployByRepositoryId/test-002
[INFO] * Upload of locally staged components done.
[INFO] * Closing staging repository with ID "test-002".
[INFO] Finished staging against Nexus with success.
Failures are accompanied by error reports that reveal further details:
[ERROR] Error while trying to close staging repository with ID "test-003". [ERROR] [ERROR] Nexus Staging Rules Failure Report [ERROR] ================================== [ERROR] [ERROR] Repository "Test-003 (u:admin, a:127.0.0.1)" (id=n/a) failures [ERROR] Rule "RepositoryWritePolicy" failures [ERROR] * Artifact updating: Repository ='releases:Releases' does not allow updating artifact='/com/sonatype/training/nexus/explicit-staging-example/t1.0.0/staging-example-1.0.0.jar' [ERROR] * Artifact updating: Repository ='releases:Releases' does not allow updating artifact='/com/sonatype/training/nexus/explicit-staging-example/1.0.0/staging-example-1.0.0.pom' [ERROR] [ERROR]
If the configuration parameter skipStagingRepositoryClose set to true is passed to the plugin execution, the remote staging repository will not be closed.
Instead of repository manager creating a staging repository based on the implicit or explicit staging profile
selection, you can explicitly configure the staging repository to use by providing the staging repository name as
value of the stagingRepositoryId configuration property via the plugin configuration or command line invocation.
The identifier of a staging repository can be determined by looking at
the name column in the list of staging repositories. The name column
used the capitalized ID and adds the username and address the staging
was deployed from in brackets. For example a name could be
Test-003 (u: admin, a: 127.0.0.1). The ID of this staging repository
is test-003.
Together with skipping the closing of the repository using
skipStagingRepositoryClose, it is possible to get multiple builds to
deploy to the same staging repository and, therefore, have a number of
components go through the staging workflow together. An alternative to
this approach would be to create an aggregating project that assembles
all components together, e.g., in an assembly and then use this project
for staging.
Finally to override all staging, you can define the full repository URL to
deploy to with the deployUrl configuration parameter. For example, see below:
http://localhost:8081/nexus/content/repositories/releases/
This would cause any staging to be skipped and a straight upload of the components to the repository to occur.
As part of the configuration section for the plugin you can define tags with arbitrary key and value names. For example, you could create a tag with key localUsername and a value of the current user picked up from the USER environment variable:
...
<configuration>
...
<tags>
<localUsername>${env.USER}</localUsername>
<javaVersion>${java.version}</javaVersion>
</tags>
...
Once components are released these tags are transformed into attributes stored along the components in the release repository and can be accessed via the REST interface and, therefore, any plugin and user interface integration.
In addition to the above documented configuration options that determine the behaviour of the Nexus Staging Maven plugin, further configuration can be provided with the following parameters:
- altStagingDirectory
-
Defaulting to target/nexus-staging you can set the property to set a different folder for the local staging.
- autoReleaseAfterClose
-
If you set this flag to true, the staging repository will be closed and, following a successful validation of all staging rules including potential {iq}-based validation, released. By default this property is set to false. Changing it to true can be a useful setup for continuous integration server based releases.
- description
-
Allows you to provide a description for the staging repository action (like close or drop) carried out as part of the plugin execution. The description will then be used in any notification just like a description provided in the user interface.
- keepStagingRepositoryOnFailure
-
Setting this flag to true will cause the plugin to skip any clean up operations like dropping a staging repository for failed uploads, by default these clean up operations occur.
- keepStagingRepositoryOnCloseRuleFailure
-
With the default setting of false, the Nexus Staging Maven plugin will drop the created staging repository if any staging rule violation occurs. If this flag is set to true, it will not drop the staging repository. This allows you to inspect the deployed components in order to figure out why a rule failed causing the staging failure.
- skipStagingRepositoryClose
-
Set this to true to turn off the automatic closing of a staging repository after deployment.
- skipNexusStagingDeployMojo
-
Set to false by default, this flag will cause to skip any execution of the 'deploy' goal of the plugin when set to true similar to 'maven.deploy.skip'. In multi-module builds the staging of all components is performed in the last module based on the reactor order. If this property is set to
truein the module, all staging will be skipped. You have to ensure that this property evaluates astruein the last module of the reactor. If necessary, you can add a dummy module. - skipStaging
-
Set to false by default this flag will cause to skip any execution of the plugin when set to true.
- skipRemoteStaging
-
If this flag is set to true any step related to remote staging will be skipped and only local staging will be performed. The default setting is false.
- skipLocalStaging
-
When true, bypass all staging specific features. Remote deploys happen inline at deploy phase of each module, not at build end. The deployment repository is "sourced" from pom.xml <distributionManagement>. Which distribution repository is used depends on the project having a release or snapshot version. Essentially this option makes the staging plugin execution act like the default 'maven-deploy-plugin'. The default setting is false.
- stagingProgressTimeoutMinutes
-
Defaulting to 5 minutes, this configuration allows you to set the timeout for staging operations. Changes are most often required for complex staging operations involving custom staging rules or {iq} integration.
- stagingProgressPauseDurationSeconds
-
The default of 3 seconds can be changed if larger pauses between progress polls for staging operations are desired.
With skipRemoteStaging set to true, only the local staging
happens. This local staging can then be picked up for the remote
staging and closing by running the deploy-staged goal of the plugin
explicitly like this
mvn nexus-staging:deploy-staged
Besides the default deploy goal the Nexus Staging Maven plugin supports a number of additional goals. By configuring executions of the goals as part of your POM or manually invoking them further automation of a staged release process can be achieved.
- deploy-staged
-
Perform full staging deployment workflow for a locally staged project, e.g., with the components in target/nexus-staging.
- deploy-staged-repository
-
Perform an upload of a repository from the local filesystem to a staging repository.
- close
-
Close the staging repository for current context.
- drop
-
Drop the staging repository for current context.
- release
-
Release the staging repository for current context.
- promote
-
Promote the staging repository for the current context.
Closing, dropping, and releasing the staging repository using the goals relies on content of a local staging folder .
Promoting additionally needs the build promotion profile name passed in
via the buildPromotionProfileId configuration parameter.
The deploy-staged-repository goal can be used to stage a repository. Typically, a local repository is created with an invocation of the deploy similar to
mvn deploy -DaltDeploymentRepository=local::default::file://path
To deploy this file system repository with the goal, you have to provide the path to this repository with the 'repositoryDirectory' parameter as well as 'nexusUrl', 'serverId' and 'stagingProfileId'. Optionally you can configure the repository to stage into with 'stagingRepositoryId'. This aggregated command can then be run outside any specific Maven project.
While the above goals need the context of a project with configuration for the Nexus Staging Plugin in the POM file, it is possible to execute staging repository-related tasks without a project as well. The Nexus Staging Maven plugin offers remote-control goals to control staging:
- rc-close
-
Close a specified staging repository.
- rc-drop
-
Drop a specified staging repository.
- rc-release
-
Release a specified staging repository.
- rc-promote
-
Promote a specified staging repository.
- rc-list
-
List all staging repositories.
When invoking these goals outside a project context, you need to have the Nexus Staging Maven plugin groupId specified as a pluginGroup in your settings.xml:
<pluginGroups> <pluginGroup>org.sonatype.plugins</pluginGroup> </pluginGroups>
In addition, you need to specify all parameters on the command line as properties passed in via -Dkey=value.
At a minimum the required parameters serverId and nexusUrl have to
be specified:
mvn nexus-staging:rc-close -DserverId=nexus -DnexusUrl=http://localhost:8081/nexus
Depending on the goal you will have to configure the staging repositories you want to close, drop or release with
-DstagingRepositoryId=repo-001,repo-002
and you can also supply a description like this
-DstagingDescription="Dropping since QA of issue 123 failed"
For promoting, you need to add the required parameter that specifies the build promotion profile identifier:
-DbuildPromotionProfileId=12a25eabf8c8b3f2
A successful remote control drop would be logged in the command line similar to this
— nexus-staging-maven-plugin:1.2:rc-drop (default-cli) @ standalone-pom — [INFO] Connecting to Nexus... [INFO] Using server credentials with ID="nexus-releases" from Maven settings. [INFO] RC-Dropping staging repository with IDs=[test-003] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------
An example usage of the rc-list goal with output is
$mvn nexus-staging:rc-list -DnexusUrl=http://localhost:8081/nexus -DserverId=nexus ... [INFO] --- nexus-staging-maven-plugin:1.5.1:rc-list (default-cli) @ standalone-pom --- [INFO] Connecting to Nexus... [INFO] Using server credentials with ID="nexus" from Maven settings. [INFO] Getting list of available staging repositories... [INFO] [INFO] ID State Description [INFO] example_release_profile-1000 OPEN Implicitly created (auto staging). ...
|
Warning
|
The Nexus Maven plugin in versions earlier than 2.1.0 had goals to work with staging repositories. These goals have been deprecated in favour of the remote control goals of the Nexus Staging Maven plugin. |
The Nexus Staging Ant tasks provide equivalent features to the Nexus Staging Maven plugin for Apache Ant users covering all use cases for interacting with the staging suite.
Historically Ant builds typically have components that are required for the build, statically managed in the version control system or even outside the project workspace altogether. More modern Ant builds use Apache Ivy or Eclipse Aether for resolving dependencies dynamically as well as deployment build outputs to a repository manager. Examples projects setups using Ivy as well as Aether can be found in the documentation examples project. This project includes examples for integration with the Nexus Staging Ant tasks.
To use the Ant tasks in your Ant build file, download the
complete JAR with the included dependencies from the Central Repository.
Simply search for 'nexus-staging-ant-tasks'
and download the JAR file with the uber classifier
e.g., nexus-staging-ant-tasks-1.6-2-uber.jar.
After downloading, put the JAR file somewhere in your project or in your system so you can add it to the classpath in your build file with a task definition. In the following example, the JAR file is placed in a tasks folder within the project.
<taskdef uri="antlib:org.sonatype.nexus.ant.staging"
resource="org/sonatype/nexus/ant/staging/antlib.xml">
<classpath>
<fileset dir="tasks" includes="nexus-staging-ant-tasks-*uber.jar" />
</classpath>
</taskdef>
To enable the tasks in your build file using a shortcut for the namespace, e.g., staging, you have to add it to the project node:
<project xmlns:staging="antlib:org.sonatype.nexus.ant.staging" ...>
The deployment-related information for your project is captured in a nexusStagingInfo section in your build file that contains all the necessary configuration.
<staging:nexusStagingInfo id="target-nexus"
stagingDirectory="target/local-staging">
<staging:projectInfo groupId="org.sonatype.nexus.ant"
artifactId="nexus-staging-ant-tasks"
version="1.0" />
<staging:connectionInfo
baseUrl="http://localhost:8081/nexus">
<staging:authentication
username="deployment"
password="deployment123" />
</staging:connectionInfo>
</staging:nexusStagingInfo>
- nexusStagingInfo:id
-
The identifier that allows you to reference the staging information in the Ant build file.
- stagingInfo:stagingDirectory
-
The local staging directory, a place where local staging will happen. Ensure that this directory is cleaned up by a clean task or alike, if any.
- projectInfo
-
The project information targetting a staging profile. This can be done explicitly with the stagingProfileId or implicitly with groupId, artifactId and version. stagingRepositoryId can also be part of projectInfo identifying a staging repository for interaction.
- connectionInfo:baseUrl
-
The base URL of the repository manager you want to deploy to and interact with.
If necessary the connectionInfo can have a nested proxy section
<staging:proxy
host="proxy.mycorp.com"
port="8080">
<staging:authentication
username="proxyUser"
password="proxySecret" />
</staging:proxy>
With the above setup you are ready to add a deploy target to your build file that stages the components locally as well as remotely and closes the staging repository.
<target name="deploy" description="Deploy: Local and Remote Staging">
<staging:stageLocally>
<staging:nexusStagingInfo
refid="target-nexus" />
<fileset dir="target/local-repo"
includes="**/*.*" />
</staging:stageLocally>
<staging:stageRemotely>
<staging:nexusStagingInfo
refid="target-nexus" />
</staging:stageRemotely>
</target>
The folder target/local-repo has to contain the components in a directory structure resembling the Maven repository format using the groupId, artifactId and version coordinates of the component mapped to directory names. It will be merged into the target release repository, when the staging repository is released. An example on how to create such a structure in Ant can be found in the staging example for Apache Ivy and Eclipse Aether in the documentation examples project.
Similarily, you can create a target that releases the staged components by adding the releaseStagingRepository task to the end of the target:
<staging:releaseStagingRepository>
<staging:nexusStagingInfo
refid="target-nexus" />
</staging:releaseStagingRepository>
The stageLocally task takes a fileset as configuration. The stageRemotely task has additional configuration options.
- keepStagingRepositoryOnFailure
-
Set to true this causes the remote staging repository to be kept rather than deleted in case of a failed upload. Default setting is false
- skipStagingRepositoryClose
-
By default a staging repository is automatically closed, setting this parameter to true will cause the staging repository to remain open.
In addition to the tasks for local and remote staging, the Nexus Staging Ant tasks include tasks for closing, dropping, releasing and promoting a staging repository:
-
closeStagingRepository
-
dropStagingRepository
-
releaseStagingRepository
-
promoteStagingRepository
All these tasks take the context information from the local staging
directory or from the optional parameter stagingRepositoryId. The
task to promote a repository has the additional, mandatory attribute
buildPromotionProfileId to specify the build promotion profile to
promote.
The timing of the task operation can be affected by the following configuration parameters:
- stagingProgressTimeoutMinutes
-
Defaulting to 5 minutes, this configuration allows you to set the timeout for staging operations. Changes are most often required for complex staging operations involving custom staging rules or {iq} integration.
- stagingProgressPauseDurationSeconds
-
The default of 3 seconds can be changed if larger pauses between progress polls for staging operations are desired.
When using the Maven Deploy plugin with the staging suite, you rely on implicit matching of the components against a staging profile based on a repository target definition.
To deploy a staged release, a developer needs to deploy to the staging URL. To configure a project to deploy to the staging URL, add the distributionManagement element to your project’s POM.
<project xmlns="http://maven.apache.org/POM/4.0.0"
...
<distributionManagement>
<repository>
<id>nexus</id>
<name>Nexus Staging Repo</name>
<url>http://localhost:8081/nexus/service/local/staging/deploy/maven2/</url>
</repository>
</distributionManagement>
...
</project>
This configuration element, distributionManagement, defines the repository to which our deployment will be made. It references the staging suite’s URL: http://localhost:8081/nexus/service/local/staging/deploy/maven2
This URL acts as a virtual repository to be published to. If a component being published matches one of the repository targets in a staging profile, that staging profile is 'activated' and a temporary staging repository is created.
Once the sample project’s distributionManagement has been set to point at the staging URL and your deployment credentials are updated in your ~/.m2/settings.xml file, you can deploy to the staging URL. To do this, run mvn deploy:
$ mvn deploy [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Building staging-test [INFO] task-segment: [deploy] [INFO] ------------------------------------------------------------------------ [INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] [INFO] Nothing to compile - all classes are up to date [INFO] [resources:testResources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] [INFO] Nothing to compile - all classes are up to date [INFO] [surefire:test] [INFO] Surefire report directory: /private/tmp/staging-test/target/surefire-reports ... [INFO] [jar:jar] [INFO] [install:install] [INFO] Installing /private/tmp/staging-test/target/staging-test-1.0.jar to \ ~/.m2/repository/com/sonatype/sample/staging-test/1.0/staging-test-1.0.jar [INFO] [deploy:deploy] altDeploymentRepository = null Uploading: http://localhost:8081/nexus/service/local/staging/deploy/maven2/\ com/sonatype/sample/staging-test/1.0/staging-test-1.0.jar 2K uploaded [INFO] Uploading project information for staging-test 1.0 [INFO] Retrieving previous metadata from nexus [INFO] repository metadata for: 'component com.sonatype.sample:staging-test' could not be found on repository: nexus, so will be created [INFO] Uploading repository metadata for: 'component com.sonatype.sample:staging-test' [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL
If the staging suite is configured correctly, any deployment to the staging URL matching a repository target configured for a staging profile should be intercepted by the staging suite and placed in a temporary staging repository. Deployment with the Maven Deploy plugin will not automatically close the staging repository. Closing the staging repository has to be done via the user interface or the Nexus Staging Maven plugin. Once this repository has been closed, it will be made available in the target group you selected when you configured the staging profile.
The Gradle build system can be used to deploy components with the Gradle Maven plugin. The Nexus Staging Ant tasks can be used in Gradle allowing full integration of the staging suite features in a Gradle build.
An example project showcasing this integration is available in the documentation examples project.
You can also upload a staged deployment via the user interface. To upload a staged deployment, select 'Staging Upload' from the mainmenu. Clicking 'Staging Upload' will show the panel shown in Manually Uploading a Staged Deployment.
To upload a component, click on 'Select Artifact(s) for Upload…' and select an components from the filesystem to upload. Once you have selected a component, you can modify the classifier and the extension before clicking on the 'Add Artifact' button. Repeat this process to upload mutltiple components for the same 'Group', 'Artifact' and 'Version' (GAV) coordinates like a JAR, the POM and maybe a sources and javadoc JAR in addition. Once you have added all the components, you can then configure the source of the Group, Artifact, Version (GAV) parameters.
If the component you are uploading is a JAR file that was created by Maven, it will already have POM information embedded in it, but if you are uploading a JAR from a vendor you will likely need to set the Group Identifier, Artifact Identifier, and Version manually. To do this, select GAV Parameters from the GAV Definition drop-down at the top of this form. Selecting 'GAV Parameters' will expose a set of form fields that will let you set the 'Group', 'Artifact', 'Version', and 'Packaging' of the components being uploaded. If you would prefer to set the Group, Artifact, and Version identifiers from a POM file that was associated with the uploaded component, select From POM in the GAV Definition drop-down. Selecting From POM in this drop-down will expose a button labeled 'Select POM to Upload'. Once a POM file has been selected for upload, the name of the POM file will be displayed in the form field below this button.
The 'Staging Upload' panel supports multiple components with the same 'Group', 'Artifact', and 'Version' identifiers. For example, if you need to upload multiple components with different classifiers, you may do so by clicking on 'Select Artifact(s) for Upload' and 'Add Artifact' multiple times. This interface also accepts an 'Artifact Bundle' which is a JAR that contains more than one component, which is documented in more detail in Artifact Bundles.
Once a staging component upload has been completely configured, click on Upload Artifact(s) button to begin the upload process. The repository manager will upload the components to the Staging URL which will trigger any staging profiles that are activated by the upload by explicity matching using the repository targets configured with the staging profiles. If a staging profile is activated, a new staging repository will be created and can be managed using the procedures outlined in Managing Staging Repositories.
With a staging profile configured and a deployment completed as outlined in Configuring the Staging Suite and Configuring Your Project for Deployment, you will have an automatically generated staging repository. A list of all staging repositories can be accessed by selecting the 'Staging Repositories' item in the 'Build Promotion' menu and is displayed in Staging Repositories List Panel.
Actions for the selected staging repository/ies in the list include options to 'Close', 'Promote', 'Release' or 'Drop'. The 'Refresh' button can be used to force a reload of the list 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 tasks, the user interface is not immediately updated. You are required to press 'Refresh' to 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 target repository configured in the staging profile.
|
Note
|
A scheduled task documented in [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 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, created date/time and updated date/time, activity indicator, 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 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 occurred in an acivity. Selecting an event displays further details about the event on the right side of the tab.
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.
For build promotion profile an additional 'Members' tab is shown. 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, 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 an 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 who needs to test a deployment.
In Confirmation and Description Dialog for Closing a Staging Repository, the description field is used to describe the release for the user who 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 {iq}.
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 components available to everyone who is referencing this group. Developers who are referencing this repository group can now test and interact with the staged components as if they were published to a Hosted repository.
While the components 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 components to a hosted repository. 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.
To view all staging repositories, click on the 'Repositories' item in the 'Views/Repositories' menu and then select 'Nexus Managed Repositories' as shown in 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 [procure].
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 the repository manager and remove any reference to this repository from the groups with which it was associated. 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 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 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]](/simpligility/nexus-book/blob/master/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 A Build Promotion Repository and its Members Panel. If you add the column 'Promoted To' to the list you will observe that the repository manager 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 that 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 that 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 components 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 components 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, the repository manager will revert the status of the staging repository from promoted to closed and make the components available via the 'QA' staging repository. The effects of promoting, dropping, and releasing components through a series of staging profiles and build promotion profiles is shown in 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 releases its components to the release repository configured in 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. 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 the repository manager to publish each staging repository to a separate hosted repository.
{pro} 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. Multilevel Staging and Build Promotion illustrates a potential use for multilevel staging:
- Stage
-
A developer publishes components to a QA staging profile that 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 that exposes the staged components to a limited set of customers who have agreed to act as beta testers for a new feature.
- Release
-
Once this 'Closed Beta' testing period is finished, the staged repository is then released and the components it contains are published to a hosted release repository and exposed via the public repository group.
To support this multilevel staging feature, you can configure Build Promotion profiles as detailed in Configuring Build Promotion Profiles. Once you have promoted a Staging Repository to a Build Promotion profile, you can drop, promote, or release the components it contains as detailed in Configuring the Staging Suite.
{pro} has the ability to define staging rules that must be satisfied to allow successful deployment or before a staging repository can be promoted.
Staging rulesets are customizable groups of rules that are validated against the components in a staging repository when the repository is closed or promoted. If any rules cannot be validated, closing or promoting the repository will fail.
A staging repository associated with a staging ruleset configured in the staging profile cannot be closed or promoted until all of the rules associated with the rulesets have been satisfied. This allows you to set standards for your own hosted repositories, and it is the mechanism that is used to guarantee the consistency of components stored in the Central Repository.
To create a Staging Ruleset, click on the 'Staging Ruleset' item in the 'Build Promotion' menu. This will load the interface shown in Creating a Staging Ruleset. The Staging Ruleset panel is used to define sets of rules that can be applied to staging profiles.
{pro} contains the following rules:
- Artifact Uniqueness Validation
-
This rule checks to see that the component being released, promoted, or staged is unique in a particular repository manager instance.
- Checksum Validation
-
This rule validates that file checksum files are present and correct for the published components.
- Javadoc Validation
-
The Javadoc Validation rule will verify that every project has a component with the javadoc classifier. If you attempt to promote a staging repository that contains components not accompanied by "-javadoc.jar" components, this validation rule will fail.
- No promote action allowed
-
This rule can be used to prevent the promotion of a staging repository to a build promotion profile. It can be used enforce a choice between releasing and dropping a staging repository only.
- No release action allowed
-
This rule can be used to prevent the direct release of a staging repository. It can be used enforce a choice between promoting and dropping a staging repository only.
- POM Validation
-
The Staging POM Validation rule will verify Project URL - project/url, Project Licenses - project/licenses and Project SCM Information - project/scm. Any of these POM elements cannot be missing or empty.
- POM must not contain 'system' scoped dependencies
-
Ensures that no dependency is using the scope system. This allows for a path definition ultimately making the component rely on a specific relative path and using it is considered bad practice and violates the idea of having all necessary components available in repositories.
- POM must not contain release repository
-
This rule can ensure that no release repository is defined in the repositories element in the POM. This is important since it potentially would circumvent the usage of the repository manager and could point to other repositories that are not actually available to a user of the component.
- Profile target matcher
-
This rule verifies the staging repository content against the repository target configured in the staging profile for this staging repository. This enforces that only components using the correct repository path as a result of the groupId.
- Signature Validation
-
The Signature Validation rule verifies that every item in the repository has a valid PGP signature. If you attempt to promote a staging repository that contains components not accompanied by valid PGP signature, this validation will fail.
- Sources Validation
-
The Sources Validation rule will verify that every project has a component with the sources classifier. If you attempt to promote a staging repository that contains components not accompanied by "-sources.jar" components, this validation rule will fail.
To define a ruleset to be used for closing or promotion, edit the staging profile by selecting it in the staging profile list. Scroll down to the sections 'Close Repository Staging Rulesets' and 'Promote Repository Staging Rulesets' as shown in Associating a Staging Ruleset with a Staging Profile and add the desired available rulesets to the left-hand list of activated rulesets for the current staging profile.
The next time you attempt to close or promote a staging repository that was created with this profile, {pro} will check that all of the rules in the associated rulesets are being followed.
As discussed in [concepts], repository management and managing components in your software development life cycle are closely related activities. The Nexus suite of tools provides a server application for administrating your component usage policies and other features that integrate with other tools of the suite. It has access to extensive security vulnerability and license information data from the {iq} backend that can be used as input for your policies. For example you could establish a policy that is logged as violated, if any component in your software has a known security vulnerability or uses a license that is incompatible with your business model.
{pro} can take advantage of {iq}. It can be integrated to validate policies as part of your usage of the staging suite.
Detailed instructions on how to install and configure the {iq} as well as the integration with {pro} can be found in the documentation.
Artifact bundles are groups of related components that are all related by the same groupId, artifactId, and version (GAV) coordinate. They are used by projects that wish to upload components to the Central Repository.
Bundles must contain the following POM elements:
-
modelVersion
-
groupId
-
artifactId
-
packaging
-
name
-
version
-
description
-
url
-
licenses
-
scm
-
url
-
connection
-
Artifact bundles are created with the Maven Repository Plugin. For more information about the Maven Repository plugin, see http://maven.apache.org/plugins/maven-repository-plugin/.
Sample POM Containing all Required Bundle Elements lists a project’s POM that satisfies all of the constraints that are checked by the Maven Repository plugin. The following POM contains a description and a URL, SCM information, and a reference to a license. All of this information is required before a component bundle can be published to the Maven Central repository.
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.sonatype.sample</groupId>
<artifactId>sample-project</artifactId>
<packaging>jar</packaging>
<version>1.0</version>
<name>sample-project</name>
<description>A Sample Project</description>
<url>http://books.sonatype.com</url>
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
<distribution>repo</distribution>
</license>
</licenses>
<scm>
<connection>
scm:git:git://github.com/sonatype/sample-project.git
</connection>
<url>http://github.com/sonatype/sample-project.git</url>
<developerConnection>
scm:git:git://github.com/sonatype-sample-project.git
</developerConnection>
</scm>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
To create a bundle from a Maven project, run the repository:bundle-create goal. This goal will check the POM to see if it complies with the standards for publishing a bundle to a public repository. It will then bundle all of the components generated by a particular build. To build a bundle that only contains the standard, unclassified component from a project, run mvn repository:bundle-create. To generate a bundle that contains more than one component, run mvn javadoc:jar source:jar repository:bundle-create:
~/examples/sample-project$ mvn javadoc:jar source:jar repository:bundle-create
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'javadoc'.
[INFO] ------------------------------------------------------------------------
[INFO] Building sample-project
[INFO] task-segment: [javadoc:jar, source:jar, repository:bundle-create]
[INFO] ------------------------------------------------------------------------
[INFO] [javadoc:jar {execution: default-cli}]
Loading source files for package com.sonatype.sample...
Constructing Javadoc information...
Standard Doclet version 1.6.0_15
Building tree for all the packages and classes...
...
[INFO] Preparing source:jar
[INFO] No goals needed for project - skipping
[INFO] [source:jar {execution: default-cli}]
...
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running com.sonatype.sample.AppTest
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.03 sec
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] [jar:jar {execution: default-jar}]
[INFO] Building jar: ~/temp/sample-project/target/sample-project-1.0.jar
[INFO] [repository:bundle-create {execution: default-cli}]
[INFO] The following files are marked for inclusion in the repository bundle:
0.) Done
1.) sample-project-1.0.jar
2.) sample-project-1.0-javadoc.jar
3.) sample-project-1.0-sources.jar
Please select the number(s) for any files you wish to exclude, or '0' when \
you're done. Separate the numbers for multiple files with a comma (',').
Selection:
0
[INFO] Building jar: ~/temp/sample-project/target/sample-project-1.0-bundle.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 11 seconds
[INFO] Finished at: Sat Oct 10 21:24:23 CDT 2009
[INFO] Final Memory: 36M/110M
[INFO] ------------------------------------------------------------------------
Once the bundle has been created, there will be a bundle JAR in the target directory. As shown in the following command output, the bundle JAR contains a POM, the project’s unclassified component, the javadoc component, and the sources component.
~/examples/sample-project$ cd target ~/examples/sample-project/target$ jar tvf sample-project-1.0-bundle.jar 0 Sat Oct 10 21:24:24 CDT 2009 META-INF/ 98 Sat Oct 10 21:24:22 CDT 2009 META-INF/MANIFEST.MF 1206 Sat Oct 10 21:23:46 CDT 2009 pom.xml 2544 Sat Oct 10 21:24:22 CDT 2009 sample-project-1.0.jar 20779 Sat Oct 10 21:24:18 CDT 2009 sample-project-1.0-javadoc.jar 891 Sat Oct 10 21:24:18 CDT 2009 sample-project-1.0-sources.jar
To upload a component bundle to {pro}, you have to have a repository target for the project configured as described in [repository-targets].
Once that is done, select 'Staging Upload' from the 'Build Promotion' section of the main menu. This will load the 'Staging Upload' tab. Choose 'Artifact Bundle' from the 'Upload Mode' drop-down. The 'Staging Upload' panel will switch to the form shown in Uploading an Artifact Bundle. Click on 'Select Bundle to Upload…' and then select the JAR that was created with the Maven repository plugin used in the previous sections. Once a bundle is selected, click on 'Upload Bundle'.
After a successful upload, a dialog displays the name of the created staging repository in a URL that links to the content of the repository. To view the staging repository, click on the 'Staging Repositories' link in the 'Build Promotion' section of the menu. You should see that the 'Staging Artifact Upload' created and closed a new staging repository as shown in Staging Repository Created from Artifact Bundle Upload. This repository contains all of the components contained in the uploaded bundle. It allows you to promote or drop the components contained in a bundle as a single unit.
Once the staging repository is closed, you can promote it to a Build Promotion Profile or release it to the target repository of the staging profile as documented in Managing Staging Repositories.