Solutions Delivery Platform

Keywords

What is a Keyword?

Keywords allow you to define variables in the Pipeline Configuration that can be referenced in your Pipeline Template. This allows you to keep templates as readable as possible by externalizing the definition of complex variables like regular expressions out of the template.

The most common use case so far for Keywords is storing regular expressions that map to common branch names in the GitFlow Branching Strategy to be used in evaluating whether or not aspects of the pipeline should execute.

In this example, we’ll use a Keyword as a feature flag externalized from the Pipeline Template to conditionally determine if a manual gate is required before the deployment to Production.

Define and Use A Keyword

Define the Keyword in the Pipeline Configuration

Update the Pipeline Configuration to:

libraries{
    maven
    sonarqube
    ansible
}

stages{
    continuous_integration{
        build
        static_code_analysis
    }
}

application_environments{
    dev{
        ip_addresses = [ "0.0.0.1", "0.0.0.2" ]
    }
    prod{
        long_name = "Production"
        ip_addresses = [ "0.0.1.1", "0.0.1.2", "0.0.1.3", "0.0.1.4" ]
    }
}

keywords{
    requiresApproval = true
}

All Keywords will be defined in the keywords block of the Pipeline Configuration.

Traditional variable setting syntax of a = b is used to define Keywords.

Update the Pipeline Template

With the continuous_integration stage defined, we can update the pipeline template to make use of it.

Update the Pipeline Template to:

continuous_integration()
deploy_to dev

if(requiresApproval){
    timeout(time: 5, unit: 'MINUTES') {
        input 'Approve the deployment?'
    }
}

deploy_to prod

This is an example to demonstrate the use of a Keyword in a Pipeline Template and not how we would recommend you enable this sort of gate in a production pipeline.

We would recommend that, in practice, the deployment library inherits this manual gate approval so that requiresApproval could be set on each Application Environment individually.

Run the Pipeline

From the Pipeline job’s main page, click Build Now in the left-hand navigation menu.

When viewing the build logs, you should see output similar to:

[Pipeline] Start of Pipeline
[JTE] Pipeline Configuration Modifications (show)
[JTE] Loading Library maven (show)
[JTE] Library maven does not have a configuration file.
[JTE] Loading Library sonarqube (show)
[JTE] Library sonarqube does not have a configuration file.
[JTE] Loading Library ansible (show)
[JTE] Library ansible does not have a configuration file.
[JTE] Obtained Pipeline Template from job configuration
[Pipeline] node
Running on Jenkins in /var/jenkins_home/workspace/single-job
[Pipeline] {
[Pipeline] writeFile
[Pipeline] archiveArtifacts
Archiving artifacts
[Pipeline] }
[Pipeline] // node
[JTE] [Stage - continuous_integration]
[JTE] [Step - maven/build.call()]
[Pipeline] stage
[Pipeline] { (Maven: Build)
[Pipeline] echo
build from the maven library
[Pipeline] }
[Pipeline] // stage
[JTE] [Step - sonarqube/static_code_analysis.call()]
[Pipeline] stage
[Pipeline] { (SonarQube: Static Code Analysis)
[Pipeline] echo
static code analysis from the sonarqube library
[Pipeline] }
[Pipeline] // stage
[JTE] [Step - ansible/deploy_to.call(ApplicationEnvironment)]
[Pipeline] stage
[Pipeline] { (Deploy To: dev)
[Pipeline] echo
performing a deployment through ansible..
[Pipeline] echo
deploying to 0.0.0.1
[Pipeline] echo
deploying to 0.0.0.2
[Pipeline] }
[Pipeline] // stage
[Pipeline] timeout
Timeout set to expire in 5 min 0 sec
[Pipeline] {
[Pipeline] input
Approve the deployment?
Proceed or Abort
Approved by admin
[Pipeline] }
[Pipeline] // timeout
[JTE] [Step - ansible/deploy_to.call(ApplicationEnvironment)]
[Pipeline] stage
[Pipeline] { (Deploy To: Production)
[Pipeline] echo
performing a deployment through ansible..
[Pipeline] echo
deploying to 0.0.1.1
[Pipeline] echo
deploying to 0.0.1.2
[Pipeline] echo
deploying to 0.0.1.3
[Pipeline] echo
deploying to 0.0.1.4
[Pipeline] }
[Pipeline] // stage
[Pipeline] End of Pipeline
Finished: SUCCESS

When reading the build logs of a JTE job, you can identify the start of stages by looking for [JTE] [Stage - *] in the output.

In this case, the log output was [JTE] [Stage - continuous_integration] indicating a Stage called continuous_integration is about to be executed.

The exercise of setting requiresApproval = false and seeing the difference is left to the reader.