Jenkins Environment Variables: Default, Local & Global

Jenkins is an open-source automation tool for building, testing, and deploying software. It supports CI/CD, enabling efficient workflows and distributed builds across multiple machines. As a Java-based program, it runs on Windows, Linux, macOS, and more, with easy web-based installation. Its vast plugin ecosystem allows customization, while environment variables enhance security and flexibility by managing data and secrets across CI/CD pipelines. In this post, we will explore how these environment variables are managed in Jenkins. We'll learn about built-in environment variables alongside their global configurations and local setups. What are environment variables in Jenkins? Environment variables in Jenkins are key-value pairs that store configuration settings, credentials, and other dynamic values used during build and deployment processes. They help make Jenkins pipelines more flexible by allowing scripts and jobs to reference variables instead of hardcoded values. These variables can be defined at different levels, including system-wide (Jenkins global settings), per-node, per-job, or within pipeline scripts. Common examples include BUILD_NUMBER, JOB_NAME, and WORKSPACE, which Jenkins automatically sets for each build. Developers can define custom environment variables using the Jenkins UI, env directive in pipelines, or external configuration files. Jenkins built-in environment variables Jenkins has multiple predefined variables, often referred to as built-in environment variables. These provide essential context about pipeline configurations by dynamically storing and managing data related to builds and jobs. We can directly access the built-in variables in the pipeline scripts to streamline workflows. They eliminate the need for hardcoding specific script values and make pipelines more adaptable. Here are the most useful built-in environment variables in Jenkins: BUILD_NUMBER: This variable represents the current build number and helps track the build's sequence in the job lifecycle. JOB_NAME: It provides the job's name and helps us identify and manage specific tasks. BUILD_URL: This variable directly links to the current build, allowing us to quickly access the logs and results. NODE_NAME: It identifies the job's agent and clarifies the distributed build environments. WORKSPACE: This points to the directory where the job's files and outputs are stored during the build process. Environment variables vs parameters in Jenkins Jenkins environment variables are predefined or custom variables that store system-wide or job-specific data. They persist throughout the build and can be accessed globally across all stages. Jenkins parameters are user-defined inputs provided at the start of a job to influence execution. Unlike environment variables, parameters must be explicitly declared in the job configuration and are set before the job starts. They allow dynamic control, such as selecting a branch or setting a threshold value for testing. Parameters define values before execution, while environment variables store values during runtime. Once the job starts, parameters can become environment variables, making them accessible like other system variables. Global environment variables in Jenkins Global environment variables in Jenkins are user-defined and accessible across all jobs and pipelines within a Jenkins instance. These variables simplify configurations by providing reusable values for commonly used settings, such as paths, credentials, or default configurations. Unlike built-in variables, users explicitly define global variables to suit specific project requirements. They are handy for maintaining consistency across multiple jobs and efficiently centralizing configurations. Let's see how to set Jenkins environment variables: Setting global environment variables using Jenkins console We can use the Jenkins console to configure the global environment variables. Navigate to: Dashboard > Manage Jenkins > System > Global Properties > Environment Variables Click on the "Environment variables" checkbox and define the desired variable names and values in the provided fields. Once saved, these variables become accessible to all jobs and pipelines within the Jenkins instance. This method can modify environment variable values without altering individual job settings. Using Groovy script to set global environment variables In Jenkins, we can programmatically set global environment variables using Groovy Scripts. Developers mainly use this method to configure complex pipeline workflows or automate specific scenarios. Open the Jenkins Script Console to define or modify global variables using the following Groovy Script: import jenkins.model.Jenkins import hudson.slaves.EnvironmentVariablesNodeProperty import hudson.slaves.NodeProperty def jenkins = Jenkins.getInstance() def globalNodeProperties = jenkins.getGlobal

Mar 28, 2025 - 15:59

Jenkins Environment Variables: Default, Local & Global

Jenkins is an open-source automation tool for building, testing, and deploying software. It supports CI/CD, enabling efficient workflows and distributed builds across multiple machines.

As a Java-based program, it runs on Windows, Linux, macOS, and more, with easy web-based installation. Its vast plugin ecosystem allows customization, while environment variables enhance security and flexibility by managing data and secrets across CI/CD pipelines.

In this post, we will explore how these environment variables are managed in Jenkins. We'll learn about built-in environment variables alongside their global configurations and local setups.

What are environment variables in Jenkins?

Environment variables in Jenkins are key-value pairs that store configuration settings, credentials, and other dynamic values used during build and deployment processes. They help make Jenkins pipelines more flexible by allowing scripts and jobs to reference variables instead of hardcoded values.

These variables can be defined at different levels, including system-wide (Jenkins global settings), per-node, per-job, or within pipeline scripts. Common examples include BUILD_NUMBER, JOB_NAME, and WORKSPACE, which Jenkins automatically sets for each build.

Developers can define custom environment variables using the Jenkins UI, env directive in pipelines, or external configuration files.

Jenkins built-in environment variables

Jenkins has multiple predefined variables, often referred to as built-in environment variables. These provide essential context about pipeline configurations by dynamically storing and managing data related to builds and jobs. We can directly access the built-in variables in the pipeline scripts to streamline workflows. They eliminate the need for hardcoding specific script values and make pipelines more adaptable.

Here are the most useful built-in environment variables in Jenkins:

BUILD_NUMBER: This variable represents the current build number and helps track the build's sequence in the job lifecycle.
JOB_NAME: It provides the job's name and helps us identify and manage specific tasks.
BUILD_URL: This variable directly links to the current build, allowing us to quickly access the logs and results.
NODE_NAME: It identifies the job's agent and clarifies the distributed build environments.
WORKSPACE: This points to the directory where the job's files and outputs are stored during the build process.

Environment variables vs parameters in Jenkins

Jenkins environment variables are predefined or custom variables that store system-wide or job-specific data. They persist throughout the build and can be accessed globally across all stages.

Jenkins parameters are user-defined inputs provided at the start of a job to influence execution. Unlike environment variables, parameters must be explicitly declared in the job configuration and are set before the job starts. They allow dynamic control, such as selecting a branch or setting a threshold value for testing.

Parameters define values before execution, while environment variables store values during runtime. Once the job starts, parameters can become environment variables, making them accessible like other system variables.

Global environment variables in Jenkins

Global environment variables in Jenkins are user-defined and accessible across all jobs and pipelines within a Jenkins instance. These variables simplify configurations by providing reusable values for commonly used settings, such as paths, credentials, or default configurations.

Unlike built-in variables, users explicitly define global variables to suit specific project requirements. They are handy for maintaining consistency across multiple jobs and efficiently centralizing configurations.

Let's see how to set Jenkins environment variables:

Setting global environment variables using Jenkins console

We can use the Jenkins console to configure the global environment variables. Navigate to:

Dashboard > Manage Jenkins > System > Global Properties > Environment Variables

Click on the "Environment variables" checkbox and define the desired variable names and values in the provided fields. Once saved, these variables become accessible to all jobs and pipelines within the Jenkins instance.

This method can modify environment variable values without altering individual job settings.

Using Groovy script to set global environment variables

In Jenkins, we can programmatically set global environment variables using Groovy Scripts. Developers mainly use this method to configure complex pipeline workflows or automate specific scenarios.

Open the Jenkins Script Console to define or modify global variables using the following Groovy Script:

import jenkins.model.Jenkins
import hudson.slaves.EnvironmentVariablesNodeProperty
import hudson.slaves.NodeProperty

def jenkins = Jenkins.getInstance()
def globalNodeProperties = jenkins.getGlobalNodeProperties()
def envVarsNodePropertyList = globalNodeProperties.getAll(EnvironmentVariablesNodeProperty.class)

def newEnvVarsNodeProperty = null
def envVars = null

if (envVarsNodePropertyList == null || envVarsNodePropertyList.size() == 0) {
    newEnvVarsNodeProperty = new EnvironmentVariablesNodeProperty()
    globalNodeProperties.add(newEnvVarsNodeProperty)
    envVars = newEnvVarsNodeProperty.getEnvVars()
} else {
    envVars = envVarsNodePropertyList.get(0).getEnvVars()
}

// Add or update environment variables
envVars.put("GLOBAL_VAR2", "global_test_value_2")
envVars.put("GLOBAL_VAR3", "global_test_value_3")

jenkins.save()

println "Environment variables set successfully."

The script above first retrieves the existing global environment variable configurations using Jenkins API. If no environment variable configuration exists, it creates a new one. The script then accesses the list of environment variables and updates or adds the specified variables (GLOBAL_VAR2 and GLOBAL_VAR3) with their corresponding values. Finally, the script saves the updated configuration, and the new variables become available across all jobs and pipelines.

To execute this script, navigate to Dashboard > Manage Jenkins > Script Console in your Jenkins instance. The Script Console provides a dedicated interface for running Groovy scripts.

Running the script successfully creates or updates the specified global environment variables in Jenkins. We can verify the values by navigating to Dashboard > Manage Jenkins > System > Global Properties > Environment Variables.

Local environment variables in Jenkins

Local environment variables in Jenkins are specific to individual jobs or pipelines. Unlike global variables, they are confined to the scope in which they are defined, making them ideal for managing job-specific configurations.

These variables are particularly useful for setting parameters that should only apply to a particular job, stage, or pipeline execution, allowing for more precise and controlled configurations.

Setting local environment variables in declarative pipelines

In Jenkins declarative pipelines, we can define local environment variables at both the pipeline level and the stage level. These variables are set within an environment block, and their scope is limited to where they are defined.

Variables defined at the pipeline level are accessible in all stages, whereas those defined at the stage level are only available within that specific stage. This scoping helps manage environment-specific configurations in a streamlined way.

For example:

pipeline {
    agent any
    environment { // accessible to all stages
        HELLO = 'WORLD'
    }
    stages {
        stage('Morning') {
            environment { // stage specific env var
                GREETING = 'Good morning!'
            }
            steps {
                echo env.HELLO // valid
                echo env.GREETING // valid
            }
        }
        stage('Afternoon') {
            steps {
                echo env.HELLO //valid
                echo env.GREETING // invalid
            }
        }
    }
}

In the example above, HELLO is a pipeline-level environment variable, so it's accessible in all stages. GREETING is a stage-specific environment variable, only available in the "Morning" stage. In the "Afternoon" stage, accessing GREETING results in an invalid output since it is out of scope.

Started by user Admin

[Pipeline] Start of Pipeline
[Pipeline] node
Running on Jenkins
in /Users/ldt/.jenkins/workspace/JenkinsPipeline1
[Pipeline] {
[Pipeline] withEnv
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Morning)
[Pipeline] withEnv
[Pipeline] {
[Pipeline] echo
WORLD
[Pipeline] echo
Good morning!
[Pipeline] }
[Pipeline] // withEnv
[Pipeline] }
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (Afternoon)
[Pipeline] echo
WORLD
[Pipeline] echo
null
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // withEnv
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

In the "Morning" stage, both HELLO and GREETING are correctly printed. HELLO is accessible globally, and GREETING is accessible within the stage where it was defined.

In the "Afternoon" stage, HELLO prints correctly, but GREETING results are null because it's not accessible outside the "Morning" stage.

Using the `withEnv()` function for stage-specific variables in Groovy script

Let's look at how the syntax changes when we use Groovy to set environment variables in Jenkins. In Groovy, environment variables can be set programmatically within a pipeline using the withEnv() function. Unlike the declarative pipeline syntax, where variables are defined in the environment block, Groovy provides more flexibility by allowing us to define and modify variables dynamically within specific stages.

Here's a similar example:

node {
    // Global environment variable
    env.HELLO = 'WORLD'

    stage('Morning') {
        // Stage-specific environment variable
        withEnv(['GREETING=Good morning!']) {
            echo env.HELLO  // valid
            echo env.GREETING  // valid
        }
    }

    stage('Afternoon') {
        echo env.HELLO  // valid
        echo env.GREETING  // invalid
    }
}

The env.HELLO variable is set globally within the node and is accessible throughout the pipeline. The withEnv() function is used within the "Morning" stage to set a stage-specific variable GREETING. This limits GREETING's scope to just that stage.

The output of the Groovy script is the same as that of the declarative pipeline. This example demonstrates the importance of scope when using local environment variables in Jenkins.