Skip to content

unleash:perform

Stanley Hillner edited this page Sep 28, 2018 · 33 revisions

Full Name

com.itemis.maven.plugins:unleash-maven-plugin:1.0.0:perform

Description

Performs a Maven release build from your current working copy. This release can be seen as an atomic operation that will be rolled back in case of an error. There is no need to call any other goals to prepare the project for the release or cleanup the project afterwards.

Attributes

  • Requires a Maven project to be executed.
  • Executes as an aggregator plugin.
  • Requires to be executed in online mode.
  • Is able to work in batch mode.
  • Available since version: 1.0.0

Default Workflow

As this plugin builds on the workflow-based processing model provided by the library Maven CDI Plugin Utils each Mojo implements its Goal by providing a default workflow for the orchestration of the involved processing Steps. Below is the default workflow for the Goal named unleash:perform.

storeScmRevision
checkProjectVersions
checkParentVersions
checkDependencies
checkPlugins
checkPluginDependencies
prepareVersions
checkAether
setReleaseVersions
addSpyPlugin
buildReleaseArtifacts
removeSpyPlugin
checkForScmChanges
tagScm
detectReleaseArtifacts
setDevVersion
serializeMetadata
installArtifacts
deployArtifacts

Release Metadata

The plugin produces some metadata during the build process which is used to feed some workflow steps with implicitly produced data from other steps. These metadata are essential for the process and are tracked until workflow internally. The information that are tracked are f.i. related to the SCM (revisions, tag name, tag name pattern) or to the release itself (repository information, release artifacts).

Since it may be useful to have these information at hand after the release build is finished, there is a serialization feature as of version 2.7.0. The metadata are written into a file called releaseMetadata.properties lying in the output directory of the project (e.g. target/releaseMetadata.properties). In case of multimodule projects the output file is generated into the output directory of the reactor module.

The Serialization of the metadata is performed by a separate workflow step called serializeMetadata which gets executed right before the installation step by default (please see the Default Workflow). You may disable this feature by overriding the workflow and removing the id of the step.

Required Parameters

Name Type Default Value Description
allowLocalReleaseArtifacts boolean true Whether release artifacts are allowed in the local repository or not.
commitBeforeTagging boolean false Whether to commit before creating the SCM tag or tag from the local working copy.
mavenHome String ${maven.home} The installation directory of the Maven instance to use for building the release.
tagNamePattern String @{project.version} The pattern for generating the name of the SCM tag.

allowLocalReleaseArtifacts

This parameter specifies whether the release build tolerates release artifacts in the local repository or not. If the parameter value is set to true then the build will resume even if artifacts with the respective release version are present in the local repository. These artifacts will be overridden when the build installs the release artifacts into your local repository.

Type: boolean
Default Value: true
User Property: unleash.allowLocalReleaseArtifacts
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("allowLocalReleaseArtifacts")
private boolean allowLocalReleaseArtifacts;

commitBeforeTagging

Set this parameter to true if your release build shall create an SCM commit on your current branch prior to create the SCM tag containing the release sources. The tag will then be created from that commit. If the parameter is set to false then the SCM tag will be created from your local working copy instead.
Creating the tag from your local working copy has the advantage that incoming commits on the remote branch won't disturb the release build which is why this has been made the default behavior.

Type: boolean
Default Value: false
User Property: unleash.commitBeforeTagging
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("commitBeforeTagging")
private boolean commitBeforeTagging;

mavenHome

The actual building of the project's release version happens in a separate Maven invocation. For this invocation the home directory of the Maven installation to be used for the release build must be specified. By default this variable is set to the same installation as used by the current build process.

Type: java.lang.String
Default Value: ${maven.home}
User Property: unleash.mavenHome
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("maven.home")
private String mavenHome;

tagNamePattern

The calculation of the SCM tag names can be influenced by a pattern. The pattern supports variable expansion as Maven does. You can use all variable references that are also usable within a Maven build but instead of wrapping the variable names in ${} you will have to use @{}.

Examples (building com.example:test:1.0.0):

Pattern Generated Tag Name
release-test release-test
@{project.version} 1.0.0
@{project.artifactId}-@{project.version} test-1.0.0
release[@{project.groupId}:@{project.artifactId}:@{project.version}] release[com.example:test:1.0.0]
@{project.build.finalName} release-test-1.0.0
release-@{project.version} (@{env.user}) release-1.0.0 (jenkins)

Type: java.lang.String
Default Value: @{project.version}
User Property: unleash.tagNamePattern
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("tagNamePattern")
private String tagNamePattern;

Optional Parameters

Name Type Default Value Description
additionalDeploymentRepositories Set<Repository> A set of remote repositories used as additional deployment repositories.
developmentVersion String The global version assigned for the preparation of the next development cycle.
goals List<String> clean,verify The goals used during the actual release build.
preserveFixedModuleVersions boolean false Whether to exclude fixed verisons from version upgrading as well as uploading.
profiles List<String> The profiles that shall be activated during release build.
releaseArgs List<String> Additional arguments to be passed to the release build.
releaseEnvironmentVariables String Additional environment variables for the release build.
releaseVersion String The global release version for all modules.
scmMessagePrefix String [unleash-maven-plugin] A prefix for SCM commit messages.
scmPassword String The password for modifying SCM access when using username/password authentication.
scmPasswordEnvVar String The name of an environment variable to retrieve the SCM password from.
scmSshPassphrase String The private key passphrase for modifying SCM access when using SSH public/private key authentication.
scmSshPassphraseEnvVar String The name of an environment variable to retrieve the private key passphrase from when using SSH public/private key authentication.
scmSshPrivateKeyEnvVar String The name of an environment variable that can be used to get the private key for SSH public/private key authentication.
scmUsername String The username for modifying SCM access when using username/password authentication.
scmUsernameEnvVar String The name of an environment variable to retrieve the SCM username from.
versionUpgradeStrategy Enum DEFAULT Sets the strategy for development version upgrading.

additionalDeploymentRepositories

This parameter can be used to specify a set of repositories that are used as additional deployment repositories of the release build.

Type: java.util.Set<com.itemis.maven.plugins.unleash.util.Repository>
Default Value:
User Property:
Valid Since: 2.9.0
Valid Until:
CDI Injection:

@Inject
@Named("additionalDeployemntRepositories")
private Set<Repository> additionalDeployemntRepositories;

The Repository type provides the following parameters:

Name Type Default Value Description
id String The id of the repository that is used to query the authentication data from the corresponding server definition of the Maven settings used for the build.
url String The url of the repository which must be enabled for release artifacts.

Usage of system properties for release repository specification

The unleash-maven-plugin adopts the system property mechanism of the multi-deploment-maven-plugin starting at version 2.9.2 and is thus capable of parsing the additional release repositories from the system properties as they are used by the multi-deploy plugin. This means that it is now possible to specify the additional release repositories as a mixture of the static plugin configuration and a set of repositories specified through system properties. The format of the property definitions is similar to the multi-deployment-maven-plugin's properties which is:

Each repository has to be specified in its own system property where the key has to start with multiDeploy.repo followed by a unique suffix per repository. The value of that property contains a comma-separated list of key-value pairs describing the repository's properties (id, url, snapshots, releases).

Sample Usage:

mvn unleash:perform -DmultiDeploy.repo1="id=nexus2,url=http://localhost:8082/nexus/content/repositories/snapshots/,releases=false" -DmultiDeploy.repo2="id=nexus3,url=http://localhost:8083/nexus/content/repositories/releases/,snapshots=false"

developmentVersion

This parameter can be used to assign a single version for the next development cycle to all modules of a multi-module project. This development version is typically a SNAPSHOT version and will be committed to the active branch from which the sources have been checked out.

Type: java.lang.String
Default Value:
User Property: unleash.developmentVersion
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("developmentVersion")
private String developmentVersion;

goals

This parameter is used to specify the Maven goals that are used during the actual release build. The default value clean,verify is justified by the fact that the installation and deployment of the release artifacts is postponed to later workflow steps in order to make the whole process reversible. The usage of this parameter is not recommended since the wrong set of goals can break the whole release process! So please handle with care.

Type: java.util.List<java.lang.String>
**Default Value:clean,verify
User Property: unleash.goals
Valid Since: 2.7.0
Valid Until:
CDI Injection:

@Inject
@Named("releaseGoals")
private List<String> goals;

preserveFixedModuleVersions

Use this parameter to indicate that modules with fixed versions (release versions) shall be excluded during the version upgrading. Furthermore these modules are not uploaded to the remote repository during deployment.

Type: boolean
Default Value: false
User Property: unleash.preserveFixedModuleVersions
Valid Since: 2.6.0
Valid Until:
CDI Injection:

@Inject
@Named("preserveFixedModuleVersions")
private boolean preserveFixedModuleVersions;

profiles

Use this parameter to specify profiles that shall be activated during the release build. This does not affect automatic profile activation as by environment variables or the presence of files.

Type: java.util.List<java.lang.String>
Default Value:
User Property: unleash.profiles
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("profiles")
private List<String> profiles;

releaseArgs

Specify additional arguments for the release build here. Arguments can be system properties (-D...), batch mode (-B), debug mode (-X) or anything else you can pass to the build.

Type: java.lang.String
Default Value:
User Property: unleash.releaseArgs
Valid Since: 1.0.0
Valid Until: 2.1.0
CDI Injection:

@Inject
@Named("releaseArgs")
private String releaseArgs;

Type: java.util.List<java.lang.String>
Default Value:
User Property: unleash.releaseArgs
Valid Since: 2.1.1
Valid Until:
CDI Injection:

@Inject
@Named("releaseArgs")
private Properties releaseArgs;

releaseEnvironmentVariables

Specify additional environment variables for the release build here. These variables are only available to the actual release build but not to the unleash run that triggers the release build. This parameter uses a map-like format:

  • environment variables consist of a key and a value which are separated by =>
  • different variable entries are listed in a comma-separated string
  • e.g. -Dunleash.releaseEnvironment="var1=>xyz, var2=>123" would set the environment variable var1 to the value xyz as well as the variable var2 to value 123

Type: java.lang.String
Default Value:
User Property: unleash.releaseEnvironment
Valid Since: 2.4.0
Valid Until:
CDI Injection:

@Inject
@Named("releaseEnvVariables")
private Map<String, String> releaseEnvVariables;

releaseVersion

This parameter can be used to assign a single release version to all modules of a multi-module project. A release version is not a SNAPSHOT version and will be used for the SCM tag that is created during the release as well as the artifacts that are created during the release build. These artifacts are then installed and deployed afterwards.

Type: java.lang.String
Default Value:
User Property: unleash.releaseVersion
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("releaseVersion")
private String releaseVersion;

scmMessagePrefix

The plugin performs some modifying SCM operations during the release build, f.i. committing the development version or creating the tag. Each of these commits gets an own message which can be prefixed to indicate the operation has been performed by the plugin. You can customize this prefix as you'd like to have it using this parameter.

Type: java.lang.String
Default Value: [unleash-maven-plugin] (since 1.0.2)
User Property: unleash.scmMessagePrefix
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("scmMessagePrefix")
private String scmMessagePrefix;

scmPassword

Modifying SCM operations usually require an authorization and sometimes it is necessary to pass the credentials to the plugin if it is not cached by the system. Use this parameter to specify your SCM password to be used during the release build.

Type: java.lang.String
Default Value:
User Property: unleash.scmPassword
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("scmPassword")
private String scmPassword;

scmPasswordEnvVar

Instead of using the scmPassword parameter and passing the password as plaintext to the plugin there is also the option to add the password to an environment variable and specify the name of this variable using this parameter. The plugin will then retrieve the password from that environment variable. If the parameter scmPassword is also set the specified password has always precedence over the one retrieved from the environment.

Type: java.lang.String
Default Value:
User Property: unleash.scmPasswordEnvVar
Valid Since: 2.1.0
Valid Until:
CDI Injection:

@Inject
@Named("scmPasswordEnvVar")
private String scmPasswordEnvVar;

scmSshPrivateKeyEnvVar

This parameter has its main application on Jenkins CI server when using SSH-based checkout with private key authentication. Regular usage of this parameter is not recommended since you are exposing your private key through an environment variable! Instead please try to utilize an Agent for your private key.

The parameter can be used to pass your private key (plain text) to the goal for SSH authentication. The key is then passed to the SCM provider. This parameter actually specifies the name of an environment variable that contains the private key.

Type: java.lang.String
Default Value:
User Property: unleash.scmSshPrivateKeyEnvVar
Valid Since: 2.6.0
Valid Until:
CDI Injection:

@Inject
@Named("scmSshPrivateKeyEnvVar")
private String scmSshPassphrase;

scmSshPassphrase

Modifying SCM operations usually require an authorization and sometimes it is necessary to pass the credentials to the plugin if it is not cached by the system. Use this parameter to specify your private key passphrase to be used for SSH public/private key authentication.

SSH-based connection is provider specific so that this parameter might have no effect for some provider implementations. Furthermore the providers might support the usage of SSH agents which make the usage of this parameter obsolete. Nevertheless, if this parameter is set it has precedence over the usage of agents.

Type: java.lang.String
Default Value:
User Property: unleash.scmSshPassphrase
Valid Since: 2.0.0
Valid Until:
CDI Injection:

@Inject
@Named("scmSshPassphrase")
private String scmSshPassphrase;

scmSshPassphraseEnvVar

Instead of using the scmSshPassphrase parameter and passing the passphrase as plaintext to the plugin there is also the option to add the passphrase to an environment variable and specify the name of this variable using this parameter. The plugin will then retrieve the passphrase from that environment variable. If the parameter scmSshPassphrase is also set the specified passphrase has always precedence over the one retrieved from the environment.

Type: java.lang.String
Default Value:
User Property: unleash.scmSshPassphraseEnvVar
Valid Since: 2.1.0
Valid Until:
CDI Injection:

@Inject
@Named("scmSshPassphraseEnvVar")
private String scmSshPassphrase;

scmUsername

Modifying SCM operations usually require an authorization and sometimes it is necessary to pass the credentials to the plugin if it is not cached by the system. Use this parameter to specify your SCM username to be used during the release build.

Type: java.lang.String
Default Value:
User Property: unleash.scmUsername
Valid Since: 1.0.0
Valid Until:
CDI Injection:

@Inject
@Named("scmUsername")
private String scmUsername;

scmUsernameEnvVar

Instead of using the scmUsername parameter and passing the username as plaintext to the plugin there is also the option to add the username to an environment variable and specify the name of this variable using this parameter. The plugin will then retrieve the username from that environment variable. If the parameter scmUsername is also set the specified username has always precedence over the one retrieved from the environment.

Type: java.lang.String
Default Value:
User Property: unleash.scmUsernameEnvVar
Valid Since: 2.1.0
Valid Until:
CDI Injection:

@Inject
@Named("scmUsernameEnvVar")
private String scmUsernameEnvVar;

VersionUpgradeStrategy

This parameter sets the strategy for the upgrade of the development version. This strategy can only be seen as a hint as it might be the case that the respective version part is not present or does not contain a numeric part that can be incremented. The determined part of the version is incremented by 1 if it exists and contains a numeric part. If the hint specifies a part that is not applicable for incrementation the fallback strategy DEFAULT is applied which increments the lowest possible (rightmost) part of the version.

Type: Enum com.itemis.maven.plugins.unleash.util.VersionUpgradeStrategy
Allowed values

  • MAJOR: Increments the major part of the version which is the first one.
  • MINOR: Increments the minor part of the version which is the second one.
  • INCREMENTAL: Increments the incremental part of the version which is the third one.
  • DEFAULT: Increments the lowest possible part of the version which is the rightmost one.

Default Value: DEFAULT
User Property: unleash.versionUpgradeStrategy
Valid Since: 2.4.0
Valid Until:
CDI Injection:

@Inject
private com.itemis.maven.plugins.unleash.util.VersionUpgradeStrategy versionUpgradeStrategy;
You can’t perform that action at this time.