The XL Deploy plugin for Jenkins CI adds three post-build actions that you can use independently or together:

  • Package an application
  • Publish a deployment package to XL Deploy
  • Deploy an application

For more information about using the plugin, refer to:

Features

  • Package a deployment archive (DAR):
    • With the artifact(s) created by the Jenkins job
    • With other artifacts or resources
  • Publish DAR packages to XL Deploy:
    • A package generated by the Package your application action
    • A package from an external location (filesystem or URL)
  • Trigger deployments in XL Deploy
  • Auto-scale deployments to modified environments
  • Execute on Microsoft Windows or Unix slave nodes
  • Create a “pipeline as code” in a Jenkinsfile (supported in version 6.1.0 and later)

Configuration in Jenkins

There are two places to configure the XL Deploy plugin for Jenkins:

  • In the global Jenkins configuration at Manage Jenkins > Configure System, you can specify the XL Deploy server URL and one or more sets of credentials. Different credentials can be used for different jobs.
  • In the job configuration page, select Post-build Actions > Add post-build action > Deploy with XL Deploy. Then, configure the actions to perform and other settings. To get information about each setting, click ? located next to the setting.

Using the plugin

Generate an application version automatically

If you practice continuous delivery, you may want to increase the version automatically after each build. To do so, you can use a Jenkins environment variable in the Version field; for example, {{$BUILD_NUMBER}}. To see the complete list of available variables, refer to Building a software project.

Optimize the plugin for parallel running deployment jobs

If you have many deployment jobs running in parallel, you can adjust the connection settings by increasing the connection pool size on the Global configuration screen. The default connection pool size is 10.

Escape characters in MAP_STRING_STRING properties

When using a property of type MAP_STRING_STRING, you can escape the ampersand character (&) and equal sign (=) using \& and \=, respectively. For example, the string a=1&b=2&c=abc=xyz&d=a&b can be replaced with a=1&b=2&c=abc\=xyz&d=a\&b.

Using Jenkinsfile

In version 6.1.0 and later, you can use the Jenkins Pipeline feature with the XL Deploy plugin for Jenkins. This feature allows you to create a “pipeline as code” in a Jenkinsfile, using the Pipeline DSL. You can then store the Jenkinsfile in a source control repository.

Create a Jenkinsfile

To start using Jenkinsfile, create a pipeline job and add the Jenkinsfile content to the Pipeline section of the job configuration.

For a detailed procedure on how to use the Jenkins Pipeline feature with the Xl Deploy plugin for Jenkins, refer to XebiaLabs XL Deploy Plugin.

For information about the Jenkinsfile syntax, refer to the Jenkins Pipeline documentation. For information about the items you can use in the Jenkinsfile, click Check Pipeline Syntax on the job.

For information about how to add steps to Jenkinsfile, refer to the Jenkins Plugin Steps documentation.

Jenkinsfile example

The following Jenkinsfile can be used to build the pipeline and deploy a simple web application to a Tomcat environment configured in XL Deploy:

 node {  
 stage('Checkout') {  
    git url: '<git_project_url>'
 }

  stage('Package') {  
    xldCreatePackage artifactsPath: 'build/libs', manifestPath: 'deployit-manifest.xml', darPath: '$JOB_NAME-$BUILD_NUMBER.0.dar'  
  }  
  stage('Publish') {  
    xldPublishPackage serverCredentials: '<user_name>', darPath: '$JOB_NAME-$BUILD_NUMBER.0.dar'
  }  
  stage('Deploy') {  
    xldDeploy serverCredentials: '<user_name>', environmentId: 'Environments/Dev', packageId: 'Applications/<project_name>/$BUILD_NUMBER.0'
  }  
}

Configure the artifact path

In version 6.1.1 of the plugin, the configuration of the artifact path specified in the package phase has changed. In version 6.1.0, the artifactPath was specified as build/libs, which was relative to the Jenkins workspace path. As of version 6.1.1, the path is specified as build, and all paths specified in the deployit-manifest.xml file are relative to the build directory.

For example, this deployit-manifest.xml section defines a jee.War file artifact that is placed at <workspace>/build/libs/PetClinic.war:

<?xml version="1.0" encoding="UTF-8"?>
<udm.DeploymentPackage version="1.0.0" application="PetPortal">
 <application />
 <deployables>
  <jee.War name="/petclinic" file="/libs/PetClinic.war"/>
 <dependencyResolution>LATEST</dependencyResolution>
 <undeployDependencies>false</undeployDependencies>
</udm.DeploymentPackage>

This is the structure of the build directory in the Jenkins workspace folder:

build
  |--libs
    |--tomcat.war
    |--tomcat.war.original
  |--deployit-manifest.xml

Note that the path of the file specified in the manifest file is libs/PetClinic.war; this is relative to the artifact path that is specified in the pipeline configuration. All artifacts should be placed at the same relative path on the disk as specified in the manifest file. The package will only contain the artifacts that are defined in deployit-manifest.xml.

Deploy the same package to two XL Deploy instances

You can publish the same deployment package using one job to two XL Deploy instances to avoid duplicate builds.

  1. Install the XL Deploy plugin version 6.1.0 or higher in Jenkins.
  2. Create a Jenkins Pipeline project.
  3. Create a Jenkinsfile and with this content:

    code {
       stage('Publish') {  
         xldPublishPackage serverCredentials: 'xld-admin',   darPath: 'app_new-1.0.dar'
         }
       stage('Publish') {  
         xldPublishPackage serverCredentials: 'xld2', darPath: 'app_new-1.0.dar'
       }
       stage('Deploy') {  
         xldDeploy serverCredentials: 'xld-admin', environmentId: 'Environments/env', packageId: 'Applications/app_new/1.0'
       }
       stage('Deploy') {  
         xldDeploy serverCredentials: 'xld2', environmentId: 'Environments/env', packageId: 'Applications/app_new/1.0'
       }
     }
    

Release notes

Version 6.1.1

Improvements

Bug fixes

  • [DEPL-10899] - xldCreatePackage does not complete if artifactsPath contains darPath

Version 6.1.0

Improvements

  • Support Jenkins Pipeline, which allows you to create a “pipeline as code” in a Jenkinsfile that can be checked into source control

Version 6.0.0

Bug fixes

  • [DEPL-10686] - Jenkins plugin for XL Deploy does not work with XLD 6.0
  • [DEPL-10605] - Deployment package properties are not listed on Jenkins 2.28 and XLD plugin for Jenkins 5.0.3

Version 5.0.3

Improvements

  • [DEPL-10105] - Support Jenkins credentials in XL Deploy plugin for Jenkins.

Bug fixes

  • [DEPL-10287] - Stack Trace for error in Jenkins is repeated.

Note: Due to Jenkins bug JENKINS-6918, while overriding credentials in a job configuration, both options (User username/password and Use stored credentials) initially appear at the same time.

Version 5.0.2

Bug fixes

  • [DEPL-9295] - Properties of type map_string_string cannot include certain characters

Version 5.0.1

Bug fixes

  • [DEPL-8961] - Fixed an issue that unintentionally caused the Jenkins plugin to fall back to the default XLD descriptor repository when creating a package

Version 5.0.0

XL Deploy 5.0.0 compatibility.

Improvements

  • [DEPL-7620] - Allow external artifact reference to be supplied in Jenkins plugin

Version 4.5.2

Bug fixes

  • [DEPL-7739] - Checking Connection in Jenkins fails when XLD version is higher than XLD Jenkins plugin
  • [DEPL-7758] - Reload XLD types for existing jobs on Jenkins slaves

Version 4.5.1

Improvements

  • [DEPL-7285] - Support deploying existing Composite packages using Jenkins
  • [DEPL-7400] - Allow XLD credentials to be overridden in a Jenkins job

Bug fixes

  • [DEPL-7184] - Publish DAR fails in mixed windows/unix master/slave setup
  • [DEPL-7254] - File system location doesn’t support referencing file on Jenkins slave

Version 4.5.0

Improvements

  • [DEPL-6550] - Add orchestrator field to Jenkins plugin configuration page
  • [DEPL-6638] - Support usage of Jenkins build parameters in Environment field

Bug fixes

  • [DEPL-4798] - Unhelpful error message when Version is not defined
  • [DEPL-4899] - Hidden deployable properties are displayed in Jenkins CI dropdowns and appear editable
  • [DEPL-5521] - Text field with size large is rendered as a single line in Jenkins UI
  • [DEPL-5986] - Jenkins plugin fails with IllegalStateException due to uninitialized descriptor registries
  • DEPL-6371] - Unhelpful error message when no deployable is defined
  • [DEPL-6974] - Intermittent error in SlaveRemoteDescriptorRegistry boot

Version 4.0.1

Bug fixes

  • [DEPL-6076] - Invalid file.Folder or www.WebContent artifact created from ZIP file

Version 4.0.0

Improvements

  • [DEPL-5587] - Add compatibility check of Jenkins plugin with XL Deploy server

Bug fixes

  • [DEPL-5863] - Jenkins plugin throws random error (Error status 401 Unauthorized) during deployment
  • [DEPL-5864] - Jenkins plugin fails with “Timeout waiting for connection from pool” when used in parallel pipeline

Version 3.9.7

Improvements

  • [DEPL-5987] - Add support for XL Deploy 4.0.0 server

Bug fixes

  • [DEPL-5396] - Unable to upload folders as ZIP using Jenkins plugin

Version 3.9.6

Improvements

  • Evaluate environment variables when computing the deployable name and resolving an artifact’s location
  • Sort environment names in drop down list

Bug fixes

  • Correct handling of recursive embedded deployables
  • Correct handling of configuration item references in the job configuration