Jenkins Artifactory Plugin - Release Management

The Artifactory plugin includes release management capabilities for Maven and Gradle jobs that use Subversion, Git or Perforce for VCS.

The plugin lets you manually stage a release build, allowing you to:

• Change values for the release and next development version
• Choose a target staging repository for deployment of the release, and
• Create a VCS tag for the release.

Staged release builds can, later on, be promoted or rolled-back, changing their release status in Artifactory and, optionally, moving the build artifacts to a different target repository.

Inside Artifactory the history of all build status change activities (staged, promoted, rolled-back, etc.) is recorded and displayed for full traceability.

Plugin Issue tracker

Plugin Source Code

Maven Release Management for Jenkins Artifactory Plugin

Release management with Maven is done entirely by the plugin and executes the Maven build only once.

These are the basic steps that the plugin performs:

1. Change the POM versions to the release version (before the build starts)
2. Trigger the Maven build (with optionally different goals)
3. Commit/push changes to the tag (Subversion) or the release branch (Git)
4. Change the POM versions to the next development version
5. Commit/push changes to the trunk

In case of a failure, the plugin will do its best to rollback the changes (local and committed).

Configure Maven Jobs

To enable release management in Maven jobs, edit the job configuration and check the "Enable Artifactory release management" checkbox.

Stage a Maven Release Build

Once the release management is enabled, Artifactory release staging link will appear in the left panel ( to authorized users)

Clicking on the release staging link will open a new page with configuration options for the release build:

The release staging page displays the last build version (the version is of the root pom and it is taken from the last non-release build).

Most of the fields in the form are filled with the default values.

Version configuration controls how the plugin changes the version in the pom files (global version for all modules, version per module or no version changes).

If create VCS tag is checked (default), the plugin will commit/push the poms with the release version to the VCS system with the commit comment. When using Git, there's also an option to create a release branch.

If the target Artifactory server is the Pro edition, the last section lets you change the target repository (the default is the release repository configured in Artifactory publisher) and to add a staging comment which will be included in the build info deployed to Artifactory.

Click on the "Build and Release to Artifactory" button to trigger the release build.

Promote a Maven Release Build

After a release build finish successfully it is possible to promote the build. This is not a required step, but very useful if you want to mark the build as released in Artifactory and to move/copy the built artifacts to another repository so the artifacts will be available for the consumers.

To activate the action either click on the icon next to the build number or on the "Artifactory Release Promotion" link on the left panel of a built release job.

Note that Artifactory Pro is required for promotion.

Clicking on the link will open the promotion page:

Select the target status (Released or Rolled-Back) of the build and optional comment to display in the build in Artifactory. To move or copy the build artifacts select the target repository.

Promote a Non-Staged Maven Build

Artifactory also allows you to promote a build that has not been through release staging.

To do so, check the Allow promotion of non-staged builds box in the build job configuration dialog.

Gradle Release Management for Jenkins Artifactory Plugin

The release management in Gradle relies on version (and other) properties managed by gradle.properties file. You add all the relevant properties to the release management configuration, and the plugin will read and modify those properties in the gradle.properties file.

These are the basic steps that the plugin performs:

1. Change the gradle.properties with release values (before the build starts)
2. Trigger the Gradle build step (with optionally different tasks and options)
3. Commit/push changes to the tag (Subversion) or the release branch (Git)
4. Change the gradle.properties with next integration values

Promote a Gradle Release Build

Promotion is same as in Maven.

Configure Gradle Jobs as part of Release Management

The release management is also available for Gradle build steps in a free style project. To enable Gradle release management, edit the free style job configuration and check "Gradle-Artifactory Integration" and then "Enabled Release Management" checkbox inside the Gradle-Artifactory integration.

Stage a Gradle Release Build as part of Release Management

Once the release management is enabled, Artifactory release staging link will appear in the left panel (to authorized users).

Clicking on the release staging link will open a new page with configuration options for the release build:

The release staging page displays the release and next development properties configured for the job. The values are read from the gradle.properties file and calculation of the release and next integration version is attempted and displayed in the text fields.

If create VCS tag is checked (default), the plugin will commit/push the poms with the release version to the VCS system with the commit comment. When using Git, if 'Use release branch' is checked, the next release version changes will be done on the branch instead of the currently checkout branch.

The last section lets you change the target repository (the default is the release repository configured in Artifactory publisher) and optional staging comment which will be included in the build info deployed to Artifactory.

Click on the "Build and Release to Artifactory" button to trigger the release build.

Configure Authorization for Jenkins Artifactory Plugin

If you're using matrix based security, you'll have to grant permissions for the release and promote actions.

The plugin adds two permission types:

1. Release - Allows the user to trigger release builds
2. Promote - Allows the user to promote a build

Variables Exposed by Release Staging

The Release Staging process exposes the following variables, which can be later used inside the build job. The variables are exposed when the release build ends.

RT_RELEASE_STAGING_VERSION - Contains the release version configured for the release.

RT_RELEASE_STAGING_NEXT_VERSION - Contains the next development version configured for the release.

RT_RELEASE_STAGING_SCM_TAG - Contains the SCM tag name configured for the release.

RT_RELEASE_STAGING_SCM_BRANCH - Contains the SCM branch name configured for the release.

Release Management - Work with Subversion

The release management supports Subversion SCM when using one checkout directory.

During the release the plugin will perform the following:

1. Commit the release version directly to the tag (if create tag is checked). The release version is not committed to the to the working branch.
2. Commit the next development version to the working branch

Release Management - Work with Git

To work with Git, the Git plugin (version 1.1.10 or later) has to be configured to build one branch AND to checkout to the same local branch. The remote URL should allow Read+Write access.

The plugin uses the git client installed on the machine and uses its credentials to push back to the remote Git repository.

During the release the plugin will perform the following:

1. If create branch is checked, create and switch to the release branch
2. Commit the release version to the current branch
3. Create a release tag
4. Push the changes
5. Switch to the checkout branch and commit the next development version
6. Push the next development version to the working branch

Note that changes will only be committed if changes were made to the files (pom files or gradle.properties)

Release Management - Work with Perforce

The release management supports Perforce SCM when using one checkout directory.

During the release the plugin will perform the following:

1. Commit the release version to the working branch and create a label pointing to the changed files (if create VCS tag is checked).
2. Commit the next development version to the working branch

Jenkins Artifactory Release Staging API

The Jenkins Artifactory Plugin exposes a Release Management API that provides access to all the features that are available through the Jenkins UI.

The format of the API is as follows:

Mandatory parameters

<Jenkins Server URL>/job/<Project Name>/artifactory/staging?<Parameters List>

where:

Maven Project Parameters

The table below details the parameters that should be provided to the API. These parameters mirror those used with the Jenkins UI.

The parameters list should have the following format: <param name1>=<param value1>&<param name2>=<param value2>...

📘

Mandatory parameters

If you do not specify any of the below parameters, the Release Management API will use the values provided by the configured Artifactory Staging User Plugin.

API Execution Example Using Curl

curl -X POST \
--user $USER:$API_TOKEN \
http://localhost:8080/job/$JOB_NAME/artifactory/staging \
-H "Content-Type: application/x-www-form-urlencoded" \
-d releaseVersion=8.0.1 \
-d nextVersion=8.1-SNAPSHOT \
-d createReleaseBranch=false \
-d createVcsTag=true \
-d tagUrl=8.0 \
-d tagComment="[artifactory-release|artifactory-release] Release version 8.0" \
-d nextDevelCommitComment=comment...

📘

Note

In the above cUrl example, please replace $USER, $API_TOKEN and $JOB_NAME with the relevant values.

Also, this will only work with a generated API Token. Using password will prompt the following error message: No valid crumb was included in the request

Gradle Project Parameters

Watch the Screencast - Jenkins Artifactory Release Integration

To see the Jenkins Artifactory Release Integration in action you can watch the following:

Configure Jenkins Artifactory Plug-in

To install the Jenkins Artifactory Plugin, go to Manage Jenkins > Manage Plugins, click on the Available tab and search for Artifactory. Select the Artifactory plugin and click Download Now and Install After Restart.

JFrog Plugin for Jenkins Configuration

To configure your JFrog Platform instance settings, go to the Jenkins System Configuration Page (Manage Jenkins > Configure System).

Click on the Add JFrog Platform Instance button to create a new JFrog instance configuration. If you'd like to set separate base URLs for Artifactory or Distribution, click on the Advanced button, and set the URLs.

⚠️

Warning

The user specified above must have Deploy permission in Artifactory. Log into Artifactory with Administrator privilege, go Security | Permissions in the Admin tab. Grant Deploy permission to the Deployer user (or perhaps better, a group to which the user belongs).

Authenticate with Artifactory and Distribution using Access Tokens or Basic Auth for Jenkins

Using the Jenkins Credentials Window, you have the option of setting an Access Tokens or Username and Password / API Key to authenticate with Artifactory.

For Access Token authentication, choose Secret text in the credentials Kind field.

For Username and Password / API Key authentication, choose Username and password in the credentials Kind field.

Configure HTTP and HTTPS proxy for Jenkins

Define HTTP or HTTPS proxy according to the following Jenkins Documentation.

📘

Note

To bypass the HTTP proxy, enable the "Bypass HTTP proxy" checkbox described above.

Work with Jenkins and Maven Builds

The Jenkins Artifactory Plugin supports Maven build projects, allowing your build jobs deploy artifacts and resolve dependencies to and from Artifactory, and then have them linked to the build job that created them.

As described below, using the Jenkins Maven Plugin, you can create either a specific Maven build project, or a freestyle project with Artifactory Maven integration.

📘

JDK compatibility

From version 3.0.0, the plugin no longer supports building with JDK 7.

📘

Maven Compatibility

The minimum Maven version supported is 3.3.9

Integration Benefits

JFrog Artifactory and Maven

Configure Maven Projects

Once you have at least one Artifactory server configure, you can configure your Maven builds using the following 3 steps:

1. Resolve Artifacts from Artifactory
2. Deploy Artifacts to Artifactory
3. Allow release management (in the Build Environment section, check "Enable Artifactory release management". Additional info here)

Resolve Artifacts from Artifactory

To resolve artifacts from Artifactory, in the Build Environment section, check "Resolve artifacts from Artifactory"

Resolve artifacts from Artifactory, can be distinguish between repositories that resolves Snapshot artifacts and repositories that resolves Release artifacts.

Deploy Artifacts to Artifactory

To deploy artifacts to Artifactory, in the Post build Actions section, add a "Deploy artifacts to Artifactory" post build action.

Build Maven Configuration

The build Goals and options should be set to clean install

Configure Freestyle Maven 3 Projects

The Jenkins Artifactory plugin supports running Maven 3 builds from freestyle projects by using a Maven 3 build step + a build environment section for the Artifactory Maven 3 integration (artifact and build information deployment). However, users are encouraged to configure the Artifactory integration using Jenkins Maven Project.