Mastering Jenkins Environment Variables for Flexible CI/CD Pipelines

Introduction to Jenkins and CI/CD

Jenkins stands as a cornerstone in the world of DevOps, providing a powerful open-source automation server essential for building, testing, and deploying software. It excels at implementing Continuous Integration and Continuous Deployment (CI/CD) pipelines, streamlining workflows, and enabling distributed builds across various machines. Being Java-based, Jenkins runs on multiple operating systems, including Windows, Linux, and macOS, offering easy web-based configuration. Its extensive plugin ecosystem allows deep customization, while environment variables are key to enhancing security, flexibility, and manageability within CI/CD processes.

This post delves into the management of environment variables within Jenkins, exploring built-in variables, global configurations, and local setups to help you create more robust and adaptable automation pipelines.

What Are Jenkins Environment Variables?

In Jenkins, environment variables are dynamic key-value pairs used to store configuration settings, credentials, build-specific data, and other values needed during the build and deployment lifecycle. They are fundamental to creating flexible Jenkins pipelines, allowing scripts and job configurations to reference these variables instead of hardcoding values.

These variables can be defined at various scopes: system-wide (through Jenkins global settings), per node (agent), per job, or even dynamically within pipeline scripts. Jenkins automatically provides several useful built-in variables for every build, offering context about the execution environment. Developers can also define custom environment variables via the Jenkins user interface, using directives within pipeline scripts, or through external configuration management.

Jenkins Built-In Environment Variables

Jenkins comes equipped with numerous predefined or built-in environment variables. These variables automatically capture essential context about the build and job configurations, dynamically storing data relevant to the current execution. Accessing these built-in variables directly within pipeline scripts simplifies workflows and eliminates the need to hardcode values, making pipelines more adaptable.

Here are some of the most commonly used built-in environment variables:

BUILD_NUMBER: Represents the unique, sequential number for the current build run, useful for tracking build history.
JOB_NAME: Provides the name of the Jenkins job currently being executed, helpful for identification and conditional logic.
BUILD_URL: Offers a direct URL link to the results page of the current build, allowing quick access to logs and artifacts.
NODE_NAME: Identifies the agent (node) where the current build is running, crucial in distributed build environments.
WORKSPACE: Specifies the absolute path to the dedicated directory (workspace) on the agent where the job checks out source code and performs its work.

Environment Variables vs. Parameters in Jenkins

While both environment variables and parameters handle dynamic values in Jenkins, they serve different purposes:

Jenkins Environment Variables: These are predefined or custom key-value pairs holding data relevant to the build environment or configuration. They can be set globally, per-job, or dynamically during a build and persist throughout its execution.
Jenkins Parameters: These are user-defined inputs specified before a job starts. They allow users to influence the build’s execution by providing values (like a branch name, deployment target, or boolean flag) when triggering the job. Parameters must be explicitly defined in the job’s configuration.

Essentially, parameters are inputs defined before execution, while environment variables store values during runtime. Importantly, once a job starts, the parameters provided by the user are typically exposed as environment variables, making them accessible within the build steps just like other environment variables.

Global Environment Variables in Jenkins

Global environment variables in Jenkins are user-defined variables accessible across all jobs and pipelines within a single Jenkins instance. They are ideal for storing common settings like tool paths, deployment endpoints, or default configurations that need to be shared and reused consistently.

Unlike built-in variables, global variables are explicitly configured by administrators to meet overarching project or organizational needs. They simplify management by centralizing configuration values, reducing redundancy and ensuring consistency across multiple jobs.

Here’s how to set them up:

Setting Global Variables via the Jenkins UI

You can configure global environment variables through the Jenkins web interface:

Navigate to the Jenkins Dashboard.
Go to Manage Jenkins > System.
Scroll down to the Global properties section.
Check the Environment variables box.
Click Add to define new variables, providing a Name and Value for each.
Click Save to apply the changes.

Once saved, these variables become available to all jobs running on the Jenkins instance. This method allows easy modification without altering individual job configurations.

Setting Global Variables Using Groovy Scripts

For more automated or complex configurations, global environment variables can be set programmatically using Groovy scripts via the Jenkins Script Console.

Navigate to Manage Jenkins > Script Console.
Execute the following Groovy script (adjust variable names and values as needed):

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 {
    // Assuming only one EnvironmentVariablesNodeProperty exists
    envVars = envVarsNodePropertyList.get(0).getEnvVars()
}

// Add or update environment variables
envVars.put("GLOBAL_VAR_NAME_1", "your_global_value_1")
envVars.put("GLOBAL_VAR_NAME_2", "your_global_value_2")

jenkins.save()

println "Global environment variables updated successfully."

This script retrieves the current global node properties, finds or creates the environment variable property set, adds or updates the specified variables (GLOBAL_VAR_NAME_1, GLOBAL_VAR_NAME_2), and saves the Jenkins configuration. These variables will then be accessible globally.

Local Environment Variables in Jenkins

Local environment variables in Jenkins are defined within the scope of a specific job or pipeline, sometimes even limited to a particular stage within that pipeline. Unlike global variables, their influence is confined, making them perfect for managing job-specific configurations or temporary values needed only for a part of the build process.

This approach allows for precise control over configurations that shouldn’t affect other jobs.

Setting Local Variables in Declarative Pipelines

In Jenkins Declarative Pipelines, local environment variables are typically defined using the environment directive. This directive can be placed at the top level of the pipeline block (making variables accessible to all stages) or within a specific stage block (limiting scope to that stage).

Example:

pipeline {
    agent any
    environment { // Pipeline-level: accessible in all stages
        APP_VERSION = '1.0.0'
    }
    stages {
        stage('Build') {
            environment { // Stage-level: accessible only within 'Build' stage
                BUILD_TOOL = 'Maven'
            }
            steps {
                echo "Building App Version: ${env.APP_VERSION}" // Accesses pipeline-level var
                echo "Using Build Tool: ${env.BUILD_TOOL}"    // Accesses stage-level var
            }
        }
        stage('Test') {
            steps {
                echo "Testing App Version: ${env.APP_VERSION}" // Accesses pipeline-level var
                // echo "Build tool was: ${env.BUILD_TOOL}" // This would result in null or error, as BUILD_TOOL is out of scope
            }
        }
    }
}

In this example, APP_VERSION is available throughout the pipeline, while BUILD_TOOL is only defined and accessible within the ‘Build’ stage. Accessing env.BUILD_TOOL in the ‘Test’ stage would yield null.

Setting Stage-Specific Variables with `withEnv()` in Scripted Pipelines

In Jenkins Scripted Pipelines (or within script blocks in Declarative Pipelines), the withEnv step provides a way to define or override environment variables for a specific block of code. Variables defined using withEnv are scoped only to the code within that block.

Example:

node {
    // Define a variable accessible within the node block
    env.DEPLOY_TARGET = 'staging'

    stage('Deploy to Staging') {
        echo "Default target: ${env.DEPLOY_TARGET}" // Accesses node-level var

        // Temporarily override or set variables for this block
        withEnv(['DEPLOY_TARGET=production', 'EXTRA_PARAM=true']) {
            echo "Inside withEnv - Target: ${env.DEPLOY_TARGET}" // Overridden value: production
            echo "Inside withEnv - Extra Param: ${env.EXTRA_PARAM}" // New variable: true
        }

        echo "Outside withEnv - Target: ${env.DEPLOY_TARGET}" // Back to original: staging
        // echo "Outside withEnv - Extra Param: ${env.EXTRA_PARAM}" // This would be null, as EXTRA_PARAM was scoped to withEnv
    }
}

Here, DEPLOY_TARGET is temporarily changed to ‘production’ only inside the withEnv block. Outside of it, it reverts to its previous value (‘staging’). The EXTRA_PARAM variable only exists within the withEnv block.

Securely Managing Secrets with Jenkins Credentials

Storing sensitive information like passwords, API keys, SSH keys, or tokens directly as plain text in environment variables (whether global or local) poses a significant security risk. Anyone with access to the Jenkins configuration or build logs could potentially expose these secrets.

To mitigate this risk, Jenkins provides the Credentials Plugin, which is typically installed by default. This plugin offers a secure, centralized way to store and manage sensitive data.

Introducing the Credentials Plugin

The Credentials Plugin allows you to store various types of credentials securely within Jenkins. Jenkins encrypts these credentials and provides mechanisms to inject them safely into your pipelines or jobs only when needed, often masking them in build logs.

Common credential types include:

Username and Password: Stores a username/password pair.
SSH Username with Private Key: Stores an SSH key (often passphrase protected) for secure remote access.
Secret Text: Stores a single secret string like an API token or password.
Secret File: Stores the content of a sensitive file (e.g., a configuration file or certificate).
Certificate: Stores certificate files for authentication or secure connections.

Credentials can be stored globally or within specific Jenkins folders or domains for finer-grained access control.

Example: Using Secret Text Credentials

Let’s say you need to use an API token in your pipeline.

Create the Credential:
- Go to Manage Jenkins > Credentials.
- Choose a store (e.g., “System”) and click Global credentials (unrestricted).
- Click Add Credentials.
- Select Secret text as the Kind.
- Set the Scope (e.g., Global).
- Enter your sensitive token into the Secret field.
- Provide a unique ID (e.g., my-api-token). This ID is used to reference the credential in pipelines.
- Optionally add a Description.
- Click Create.

Use the Credential in a Pipeline:
You can securely access this credential within your pipeline using the credentials() helper method inside an environment block or the withCredentials step.

pipeline {
    agent any
    environment {
        // Assign the secret credential to an environment variable
        API_TOKEN = credentials('my-api-token')
    }
    stages {
        stage('Call API') {
            steps {
                // Use the environment variable. Jenkins masks the actual value in logs.
                sh 'curl -H "Authorization: Bearer ${env.API_TOKEN}" https://api.example.com/data'
                echo "API Token variable used (value is masked in logs): ${env.API_TOKEN}"
            }
        }
    }
}

When this pipeline runs, the actual value of the API_TOKEN will be available to the curl command, but if echoed or used in contexts Jenkins recognizes as potentially logging, it will appear as **** in the console output, enhancing security.

Additional Credential Management Plugins

Jenkins’ ecosystem offers further plugins for advanced credential management, often integrating with external secret stores:

Credentials Binding Plugin: Allows binding credentials to environment variables or temporary files more directly within steps.
Kubernetes Credentials Provider: Fetches secrets directly from Kubernetes secrets.
AWS Secrets Manager Credentials Provider: Integrates Jenkins with AWS Secrets Manager, allowing credentials stored there to be used in pipelines.
HashiCorp Vault Plugin: Allows Jenkins to retrieve secrets securely from HashiCorp Vault.

How to View Jenkins Environment Variables

Understanding the environment variables available during a build is crucial for debugging pipelines and verifying configurations. Jenkins provides straightforward ways to view them:

Viewing via Web Browser (`env-vars.html`)

The quickest way to see a comprehensive list of environment variables available to Jenkins jobs (including built-in and global variables) is via a special URL:

[Your Jenkins URL]/env-vars.html

For a Jenkins instance running locally on the default port, this would be:

http://localhost:8080/env-vars.html

Navigating to this page in your browser displays a list of available environment variables and their current values within the context of the Jenkins master/controller. Note that agent-specific variables might not be fully represented here.

Viewing via a Pipeline Job

To see the environment variables exactly as they appear within the context of a specific job running on a specific agent, you can run a simple pipeline job:

Create a New Pipeline Job: Go to Jenkins Dashboard > New Item, enter a name (e.g., View Env Vars), select Pipeline, and click OK.

Set up the Pipeline Script: In the Pipeline section, paste the following script. Use sh for Linux/macOS agents or bat for Windows agents.

For Linux/macOS:

pipeline {
    agent any
    stages {
        stage('Display Environment Variables') {
            steps {
                sh 'printenv | sort' // 'printenv' or 'env' lists variables, 'sort' makes it readable
            }
        }
    }
}

For Windows:

pipeline {
    agent any
    stages {
        stage('Display Environment Variables') {
            steps {
                bat 'set' // 'set' lists variables on Windows
            }
        }
    }
}

Save and Build: Click Save, then click Build Now.
View Console Output: Once the build completes, click on the build number in the Build History and then select Console Output. The output will contain a list of all environment variables accessible to that specific build run.

Overriding Jenkins Environment Variables

Overriding environment variables allows for dynamic customization of pipeline behavior without changing the core script logic. This is useful for:

Customizing Builds: Changing paths, configurations, or feature flags for specific runs or environments.
Managing Credentials: Injecting different credentials based on the deployment target (though the Credentials plugin is the preferred secure method).
Testing and Debugging: Temporarily setting specific values to test different scenarios or debug issues.

Jenkins applies rules regarding which variable definitions take precedence:

Variables set inside a withEnv block generally override variables defined outside it (including global, pipeline-level, or stage-level).
Variables defined using the env. syntax (often in Scripted Pipelines or script blocks) can override other variables set using env..
Variables set in a Declarative environment {} block cannot typically be overridden by assignments using the env. object within the same scope, reinforcing the declarative nature.

Common methods to override variables include:

Global Configuration: Setting a variable in Manage Jenkins > System > Global properties can override default built-in values or provide a baseline that might be overridden later by job-specific settings.
Pipeline environment {} Block: Defining a variable at the pipeline or stage level overrides any global variable with the same name within that scope.
withEnv() Step: Using withEnv provides the most localized and temporary override, effective only within its block.

Conclusion

Jenkins environment variables are a powerful mechanism for creating flexible, maintainable, and secure CI/CD pipelines. By understanding the difference between built-in, global, and local variables, and knowing how to manage scope, you can tailor your automation workflows effectively. Properly utilizing the Credentials Plugin is crucial for handling sensitive data securely. Whether configuring builds, managing deployments, or debugging issues, mastering Jenkins environment variables is key to leveraging the full potential of Jenkins automation.

How Innovative Software Technology Can Help

At Innovative Software Technology, we specialize in optimizing DevOps workflows and maximizing the efficiency of CI/CD pipelines using tools like Jenkins. Our experts can help your organization effectively implement and manage Jenkins environment variables, ensuring flexible configurations and robust automation. We provide tailored solutions for secure credential management using the Jenkins Credentials Plugin and integrations with external secret managers, enhancing your pipeline security. Partner with us to streamline your build and deployment processes, implement best practices for Jenkins configuration, and achieve seamless, secure, and scalable software delivery tailored to your specific needs.