A Definitive Guide to Jenkins Pipeline Environment Variables

Welcome to the first article of the "Jenkins CookBook" series, focusing on effectively using Jenkins Pipeline environment variables. You will learn how to list, read, set, store boolean values, and capture shell command output in environment variables.

Main contents:

Listing environment variables

Reading environment variables

Setting environment variables

Overriding environment variables

Storing boolean values in environment variables

Capturing shell command output in environment variables

1. Listing environment variables

You can list all available environment variables either by opening the ${YOUR_JENKINS_HOST}/env-vars.html page on the Jenkins master or by executing the printenv shell command.

pipeline {
    agent any
    stages {
        stage("Env Variables") {
            steps {
                sh "printenv"
            }
        }
    }
}

Using printenv | sort can give a sorted list.

2. Reading environment variables

Environment variables can be accessed via the env object, e.g., env.BUILD_NUMBER. The short form BUILD_NUMBER works but may be confusing because it lacks the explicit env context.

pipeline {
    agent any
    stages {
        stage("Env Variables") {
            steps {
                echo "The build number is ${env.BUILD_NUMBER}"
                echo "You can also use ${BUILD_NUMBER}"
                sh 'echo "I can access $BUILD_NUMBER in shell command as well."'
            }
        }
    }
}

3. Setting environment variables

Declaratively set variables with an environment {} block, or imperatively with env.VARIABLE_NAME or withEnv([...]).

pipeline {
    agent any

    environment {
        FOO = "bar"
    }

    stages {
        stage("Env Variables") {
            environment {
                NAME = "Alan"
            }
            steps {
                echo "FOO = ${env.FOO}"
                echo "NAME = ${env.NAME}"
                script {
                    env.TEST_VARIABLE = "some test value"
                }
                echo "TEST_VARIABLE = ${env.TEST_VARIABLE}"
                withEnv(["ANOTHER_ENV_VAR=here is some value"]) {
                    echo "ANOTHER_ENV_VAR = ${env.ANOTHER_ENV_VAR}"
                }
            }
        }
    }
}

4. Overriding environment variables

The withEnv([...]) block can override any variable. Variables defined in an environment {} block cannot be overridden by imperative env.VAR = "value". Imperative assignments can only override variables created imperatively.

pipeline {
    agent any

    environment {
        FOO = "bar"
        NAME = "Joe"
    }

    stages {
        stage("Env Variables") {
            environment {
                NAME = "Alan" // overrides pipeline level NAME
                BUILD_NUMBER = "2" // overrides default BUILD_NUMBER
            }
            steps {
                echo "FOO = ${env.FOO}"
                echo "NAME = ${env.NAME}"
                echo "BUILD_NUMBER = ${env.BUILD_NUMBER}"
                script {
                    env.SOMETHING = "1"
                }
            }
        }

        stage("Override Variables") {
            steps {
                script {
                    env.FOO = "IT DOES NOT WORK!" // cannot override pipeline-level FOO
                    env.SOMETHING = "2" // can override imperative variable
                }
                echo "FOO = ${env.FOO}"
                echo "SOMETHING = ${env.SOMETHING}"
                withEnv(["FOO=foobar"]) {
                    echo "FOO = ${env.FOO}"
                }
                withEnv(["BUILD_NUMBER=1"]) {
                    echo "BUILD_NUMBER = ${env.BUILD_NUMBER}"
                }
            }
        }
    }
}

5. Storing boolean values in environment variables

All environment variable values are stored as strings. To use a boolean false correctly in a condition, call .toBoolean() on the string.

pipeline {
    agent any
    environment {
        IS_BOOLEAN = false
    }
    stages {
        stage("Env Variables") {
            steps {
                script {
                    if (env.IS_BOOLEAN) {
                        echo "This prints because \"false\" string is truthy"
                    }
                    if (env.IS_BOOLEAN.toBoolean() == false) {
                        echo "This prints because \"false\".toBoolean() is false"
                    }
                }
            }
        }
    }
}

6. Capturing shell command output in environment variables

Use sh(script: 'cmd', returnStdout: true) to capture command output and assign it to an environment variable.

pipeline {
    agent any
    environment {
        LS = "${sh(script:'ls -lah', returnStdout: true)}"
    }
    stages {
        stage("Env Variables") {
            steps {
                echo "LS = ${env.LS}"
            }
        }
    }
}

For any questions, reply to the public account.