Jenkins plugin

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:

• Get started with DevOps as Code and the XL CLI
• Using XL CLI wrapper scripts

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:

• Create a deployment package using Jenkins
• The Deploy plugin on the Jenkins wiki

Features

• 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 Digital.ai 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 />
 <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

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'
  }
}