An introduction to Jenkins environment variables, parameters and use of groovy scripts.

Photo by Bram Naus on Unsplash

An introduction to Jenkins environment variables, parameters and use of groovy scripts.

An introduction to Jenkins environment variables, parameters and use of groovy scripts.

This is the third article in the series Deploy a Django app to AWS EC2 instance using Jenkins. A gentle guide to Jenkins.

In this article, we will go through how to use variables and parameters in Jenkins and how to use groovy scripts. We will be using the same project as before. You are required to have gone through the previous articles beforehand.

1. How to configure and use variables in a JenkinsFile.

While writing a JenkinsFile pipeline script, you may need to inject and use some dynamic values thus avoiding the hassle of hardcoding values in the pipeline hence the need for environment variables.

Jenkins environment variable is a global variable, exposed via env variable and used in Jenkins pipelines and anywhere in your Jenkinsfile file /Pipeline. Any value stored as the environment variable in the env variable is of string type.

Jenkins already has a list of pre-defined environment variables that you can use in your pipeline. A comprehensive list of the variables can be found by accessing the below URL on your browser.

${JENKINS_IP}/env-vars.html/
// Substitute JENKINS_IP with the IP address of the digital ocean droplet hosting our Jenkins server.

You should expect to see a page with all the Jenkins env variables.

Screenshot from 2022-08-30 17-24-57.png

Now that you can access a list of the environment variables, let us now access them in our JenkinsFile.

To access the environment variables in our JenkinsFile, we use the env object. The reference to Jenkins pipeline environment variables is made by surrounding it by${} in the following way: ${env.ENV_VARIABLE}

Let us now add an init stage in the JenkisFile where we can see this in use.

stage('Init') { 
            steps { 
                echo "Hello, this is build number ${env.BUILD_NUMBER}"
            }
        }

You can also access the environment variables without the env object

stage('Init') { 
            steps { 
                echo "Hello, this is build number ${BUILD_NUMBER}"
            }
        }

However, for pre-defined variables, it is common practice to access them with the env object.

Local environment variables in Jenkins

You can also define your own environment variables in a JenkinsFile Script. This is done by adding your variable to an environment block.

pipeline {
   agent any
   environment {
       DISABLE_AUTH = 'true'                               //can be used in whole pipeline
   }
   stages {
       stage(“Build”) {
           steps {
               echo env.DISABLE_AUTH
           }
       }
   }
}

You can also define local environment variables for a specific stage

pipeline {
   agent any
   environment {
       DISABLE_AUTH = 'true'
   }
   stages {
       stage(“Build”) {
           environment {
                   ENABLE_AUTH =false//can be used in this stage only
              }
           steps {
               echo env.DISABLE_AUTH
               echo env.ENABLE_AUTH
           }
       }
   }
}

You can also access credentials created via the GUI in the environment block. However, that is out of the scope of this article.

2. Parameters in your Jenkins.

You can also provide parameters in your Jenkins script. The parameters can be of the following types.

  1. String parameters.
  2. Boolean parameters.
  3. Multi-line string parameters.
  4. Choice parameters.

For the purpose of this article, we are going to see a use case which involves the use of choice parameters.

pipeline { 

    agent any
    parameters { 
        choice(name: 'Version', choices:['1.1.0', '1.2.0', '1.3.0'], description:'')
    }
    stages { 

        stage('Init') { 

            steps { 

                echo "Hello, this is build number ${BUILD_NUMBER}"
            }
        }
        stage("deploy"){ 
            steps{
                echo "Deploying Version ${VERSION}"
            }
        }
    }
}

You can now head over to the Jenkins dashboard and you will see a build with parameters option and which upon selecting the version a build will commence.

Screenshot from 2022-08-30 18-29-38.png

Disclaimer: This is simple into to parameters in Jenkins, a more in-depth article on the same is in the works.

  1. Refactor the build step into a groovy script.

You will now start decomposing and refactoring the build step in our JenkisFile by moving the docker build commands into a groovy script. You can read more about the groovy scripts and its use-case in Jenkins in the documentation

Create a file named script.groovy at the root of the project and add the following code to it.

def buildApp() { 
    echo "Building app"
}
return this

To use this script in your JenkinsFile, add a script block in the init stage and load the file as follows.

        stage('Init') { 

            steps { 
                script { 
                    gv = load "script.groovy"
                }
            }
        }

To make this globally available we can define it at the top of our file.

def gv 
pipeline { 

    agent any
    parameters { 
        choice(name: 'Version', choices:['1.1.0', '1.2.0', '1.3.0'], description:'')
    }
    stages { 

        stage('Init') { 

            steps { 
                script { 
                    gv = load "script.groovy"
                }
            }
        }
        stage("deploy"){ 
            steps{
                echo "Deploying Version ${VERSION}"
            }
        }
    }
}

You are now able to access the buildApp function defined in the script.groovy file by:

stage('build') { 
            steps{
                scripts { 
                    gv.buildApp()
                }
            }
        }

Commit your code to version control and run a new build and it should pass.

We have introduced a new concept, the use of groovy scripts and this will be fully discussed in the next article.

At this stage, you should be fairly comfortable with using environment variables and parameters in Jenkins and should have a basic knowledge of the use case of groovy scripts and its importance. In the next article, we will now write a Jenkins file that builds, run tests and pushes our docker image to dockerhub by building on the foundations we have gone through today ( env variables, parameters, user inputs and use of groovy scripts.). We shall also set up email notifications to notify us of the build status (success/failure).

Happy hacking.