Jenkins plugin

Important: This topic describes using a CI tool plugin to interact with Deploy. However, as a preferred alternative starting with version 9.0, you can utilize a wrapper script to bootstrap XL CLI commands on your Unix or Windows-based Continuous Integration (CI) servers without having to install the XL CLI executable itself. The script is stored with your project YAML files and you can execute XL CLI commands from within your CI tool scripts. For details, see the following topics:

About the plugin

The 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 Deploy
  • Deploy an application

For more information about using the plugin, see:


  • Package a deployment archive (DAR):

    • With the artifact(s) created by the Jenkins job
    • With other artifacts or resources
  • Publish DAR packages to Deploy:

    • A package generated by the Package your application action
    • A package from an external location (filesystem or URL)
  • Trigger deployments in Deploy
  • Auto-scale deployments to modified environments
  • Execute on Microsoft Windows or Unix slave nodes
  • Create a “pipeline as code” in a Jenkinsfile

Configuration in Jenkins

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

  • In the global Jenkins configuration at Manage Jenkins > Configure System, you can specify the 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 Deploy. Configure the actions you want 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 and want to increase the version automatically after each build, you can use a Jenkins environment variable in the Version field. Example: {{$BUILD_NUMBER}}. To view the complete list of available variables, see Building a software project.

Optimize the plugin for parallel running deployment jobs

If you have multiple 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. 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

You can use the Jenkins Pipeline feature with the Deploy plugin for Jenkins. With this feature, you can 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 use the 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 Deploy plugin for Jenkins, see XebiaLabs Deploy Plugin.

For information about the Jenkinsfile syntax, see 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, see 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 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

The artifactPath is the configuration of the artifact path. This is specified as build and all paths specified in the deployit-manifest.xml file are relative to the build directory.

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 />
  <jee.War name="/petclinic" file="/libs/PetClinic.war"/>

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


Note: 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 Deploy instances

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

  1. Install the 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 7.5.8

Bug fixes

  • XLINT-896 Fix Jenkins security form validation permission

Version 7.5.7

Bug fixes

  • XLINT-890 Fix “Override Credentials” when logging in Deploy

Version 7.5.6

Bug fixes

  • XLINT-729 - Add check credentials

Version 7.5.5


  • Fixed CSRF vulnerability and permission issue

Version 7.5.4


  • XLINT-663 - Expose publish workflow action through Jenkins API

Version 7.5.3


  • XLINT-397 - Fix fatal error while promotion starts

Version 7.5.2


  • DEPL-13752 - Support credentials in all possible scope.

Version 7.5.1


  • REL-6772 - Making overrideCredentialId optional in Jenkinsfile.

Version 7.5.0


  • DEPL-12826 - Add override credentials in Jenkinsfile
  • DEPL-12305 - Optimization in getting logs of steps.

Version 6.1.1


Bug fixes

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

Version 6.1.0


  • 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 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


  • [DEPL-10105] - Support Jenkins credentials in 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 mapstringstring 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

Deploy 5.0.0 compatibility.


  • [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


  • [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


  • [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


  • [DEPL-5587] - Add compatibility check of Jenkins plugin with 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


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

Bug fixes

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

Version 3.9.6


  • 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