Environment variables access in Jenkins - Deep Dive

Overview - Environment variables access

What is it?

Environment variables are named values stored by the operating system or Jenkins that scripts and programs can use. In Jenkins, these variables hold information like build numbers, workspace paths, or user-defined data. Accessing them means reading or using these values inside Jenkins pipelines or jobs. This helps customize and control how builds run without hardcoding values.

Why it matters

Without environment variables, every Jenkins job would need fixed, hardcoded values, making automation rigid and error-prone. Environment variables let you write flexible, reusable pipelines that adapt to different builds, branches, or environments. This saves time, reduces mistakes, and makes your automation smarter and easier to maintain.

Where it fits

Before learning environment variables, you should understand basic Jenkins jobs and pipeline syntax. After mastering environment variables, you can learn about Jenkins credentials, parameterized builds, and advanced pipeline scripting to create dynamic and secure automation.

Mental Model

Core Idea

Environment variables are like labeled boxes holding information that Jenkins jobs can open and use anytime during a build.

Think of it like...

Imagine a kitchen where each labeled jar holds an ingredient. Instead of guessing or hardcoding recipes, the cook grabs the right jar by its label to make the dish. Environment variables are those labeled jars for Jenkins jobs.

┌─────────────────────────────┐
│ Jenkins Job / Pipeline      │
│                             │
│  ┌───────────────┐          │
│  │ Environment   │          │
│  │ Variables     │          │
│  │ ┌───────────┐ │          │
│  │ │ BUILD_ID  │ │          │
│  │ │ WORKSPACE │ │          │
│  │ │ USER      │ │          │
│  │ └───────────┘ │          │
│  └───────────────┘          │
│                             │
│ Uses values to control build │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What are environment variables

Concept: Introduce the basic idea of environment variables as named values accessible during Jenkins builds.

Environment variables are like labels with values stored by Jenkins or the operating system. For example, Jenkins automatically sets variables like BUILD_NUMBER (the current build count) or WORKSPACE (the folder where the build runs). These variables can be used inside your Jenkins job to get information about the build or environment.

Result

You understand that environment variables hold important data Jenkins provides automatically during builds.

Knowing that environment variables are pre-set values helps you realize you can use them to make your builds smarter without extra setup.

2

Foundation

How to access variables in Jenkins pipeline

Concept: Learn the syntax to read environment variables inside Jenkins scripted or declarative pipelines.

In a Jenkins pipeline, you access environment variables using the 'env' object. For example, to print the build number, you write: `echo "Build number is ${env.BUILD_NUMBER}"`. This syntax works in both scripted and declarative pipelines. You can also assign variables from 'env' to local variables for easier use.

Result

You can read and use environment variables inside your Jenkins pipeline scripts.

Understanding the 'env' object as the gateway to environment variables unlocks dynamic pipeline scripting.

3

Intermediate

Using custom environment variables

🤔Before reading on: do you think you can create environment variables inside a Jenkins pipeline that persist across stages? Commit to your answer.

Concept: Learn how to define your own environment variables inside Jenkins pipelines and how their scope works.

You can define custom environment variables inside the 'environment' block in declarative pipelines or by setting them in scripted pipelines. For example: environment { MY_VAR = 'hello' } This variable is then accessible as `env.MY_VAR` in all stages. However, variables set inside a shell script step do not persist outside that step unless explicitly exported and captured.

Result

You can create and use your own environment variables to pass data between pipeline steps.

Knowing where and how to define custom variables helps you control data flow in your pipeline and avoid scope confusion.

4

Intermediate

Accessing environment variables in shell steps

🤔Before reading on: do you think environment variables set inside a shell step automatically affect the Jenkins pipeline environment? Commit to your answer.

Concept: Understand how environment variables behave inside shell or batch script steps and how to pass values back to Jenkins.

Inside a shell step, you can access environment variables like `$BUILD_NUMBER` on Linux or `%BUILD_NUMBER%` on Windows. But if you set a variable inside the shell script, it only exists for that script's process and does not change Jenkins' environment. To pass values back, you can write to a file or use Jenkins features like 'withEnv' or 'envInject' plugins.

Result

You know the difference between environment variables in Jenkins and those inside shell scripts, avoiding confusion.

Understanding process boundaries prevents bugs where variables seem to disappear after shell steps.

5

Advanced

Securing environment variables with credentials

🤔Before reading on: do you think all environment variables are safe to print in logs? Commit to your answer.

Concept: Learn how Jenkins handles sensitive environment variables using credentials and masking.

Jenkins lets you store secrets like passwords or tokens securely using the Credentials plugin. These secrets can be injected as environment variables during builds but are masked in logs to prevent leaks. For example, using `withCredentials` you can bind a secret to an env variable and use it safely in your pipeline without exposing it.

Result

You can handle sensitive data securely in environment variables during Jenkins builds.

Knowing how to protect secrets in environment variables is critical for secure automation and compliance.

6

Expert

Dynamic environment variables and pipeline efficiency

🤔Before reading on: do you think environment variables can be changed dynamically during a pipeline and affect subsequent steps? Commit to your answer.

Concept: Explore how environment variables can be dynamically updated and the impact on pipeline execution and caching.

While environment variables defined in the 'environment' block are static for the pipeline run, you can dynamically update variables using script steps and the 'env' object. However, changes to 'env' at runtime may not propagate to all steps or parallel branches as expected. Understanding this helps optimize pipeline design, avoid stale values, and improve build caching and performance.

Result

You can write pipelines that adapt environment variables dynamically while avoiding common pitfalls.

Knowing the limits of dynamic env variable updates prevents subtle bugs and improves pipeline reliability.

Under the Hood

Jenkins environment variables are stored in a map-like structure called 'env' inside the pipeline runtime. When a build starts, Jenkins populates this map with default variables from the system, job configuration, and plugins. During pipeline execution, accessing 'env.VAR_NAME' reads from this map. Shell steps spawn separate processes inheriting these variables as OS environment variables. Variables set inside shell steps do not update the Jenkins 'env' map unless explicitly communicated back.

Why designed this way?

This design separates Jenkins internal state from external shell environments to maintain clear boundaries and security. It allows Jenkins to control and inject variables consistently while letting shell scripts run in isolated processes. This separation prevents accidental leaks or overwrites and supports multi-platform builds. Alternatives like sharing a single environment would risk security and cause unpredictable behavior.

┌───────────────┐       ┌───────────────┐
│ Jenkins 'env' │──────▶│ Pipeline Code │
│  Map of Vars  │       └───────────────┘
└──────┬────────┘               │
       │                        │
       │ Injects OS env vars    │
       ▼                        ▼
┌───────────────┐       ┌───────────────┐
│ Shell Process │       │ Other Plugins │
│  (inherits)   │       │  Access Vars  │
└───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: do you think setting a variable inside a shell step changes the Jenkins pipeline environment? Commit yes or no.

Common Belief: If I set an environment variable inside a shell script step, it will be available in the next pipeline step automatically.

Reality: Variables set inside a shell script only exist in that script's process and do not affect the Jenkins pipeline environment outside that step.

Why it matters: Assuming shell-set variables persist causes bugs where later steps see missing or default values, breaking pipelines unexpectedly.

Quick: do you think all environment variables are safe to print in Jenkins logs? Commit yes or no.

Common Belief: All environment variables can be safely printed in logs since they are just data.

Reality: Some environment variables hold secrets like passwords or tokens and should never be printed; Jenkins masks these when handled properly.

Why it matters: Printing secrets in logs risks exposing sensitive data, leading to security breaches and compliance failures.

Quick: do you think environment variables defined in the 'environment' block can be changed dynamically during a pipeline run? Commit yes or no.

Common Belief: Environment variables set in the 'environment' block can be updated anytime and affect all subsequent steps.

Reality: Variables in the 'environment' block are static for the build; dynamic changes to 'env' may not propagate as expected.

Why it matters: Expecting dynamic updates to static variables leads to stale data usage and confusing pipeline behavior.

Quick: do you think Jenkins environment variables come only from Jenkins itself? Commit yes or no.

Common Belief: All environment variables in Jenkins pipelines are created by Jenkins internally.

Reality: Environment variables come from multiple sources: Jenkins, the operating system, plugins, and user-defined inputs.

Why it matters: Ignoring external sources can cause unexpected variable values or conflicts, making debugging harder.

Expert Zone

1

Some plugins inject environment variables at runtime, which can override or add to Jenkins defaults, affecting pipeline behavior subtly.

2

Parallel pipeline branches may have isolated environment variable scopes, so changes in one branch do not affect others.

3

Using environment variables for secrets requires careful masking and avoiding accidental exposure in logs or error messages.

When NOT to use

Avoid relying on environment variables for complex data structures or large data; use files or Jenkins parameters instead. For secrets, prefer Jenkins Credentials plugin over plain environment variables. When needing cross-job data sharing, use artifacts or external storage rather than environment variables.

Production Patterns

In production, environment variables are used to inject configuration like API endpoints, credentials (via credentials binding), and build metadata. Pipelines often combine static environment blocks with dynamic scripted updates for flexibility. Masking secrets and limiting variable scope are standard practices to secure builds.

Connections

Operating System Environment Variables

Environment variables in Jenkins build on the OS environment variable concept by adding Jenkins-specific variables and scope.

Understanding OS environment variables helps grasp how Jenkins inherits and extends them for build automation.

Secrets Management

Environment variables often carry secrets, linking Jenkins environment variable access to secure secrets management practices.

Knowing secrets management principles clarifies why Jenkins masks sensitive environment variables and how to handle them safely.

Software Configuration Management

Environment variables are a key method for configuring software behavior dynamically, connecting Jenkins pipelines to broader configuration management strategies.

Recognizing environment variables as configuration tools helps integrate Jenkins automation with system-wide configuration best practices.

Common Pitfalls

#1 Setting environment variables inside a shell step and expecting them to persist in later pipeline steps.

Wrong approach:

sh '''
export MY_VAR=hello
'''
echo "Value is ${env.MY_VAR}"

Correct approach:

environment {
MY_VAR = 'hello'
}
echo "Value is ${env.MY_VAR}"

Root cause:

Misunderstanding that shell environment changes do not propagate back to Jenkins pipeline environment.

#2 Printing sensitive environment variables directly in pipeline logs.

Wrong approach:

echo "Password is ${env.PASSWORD}"

Correct approach:

withCredentials([string(credentialsId: 'pwd-id', variable: 'PASSWORD')]) {
sh 'use password without printing'
}

Root cause:

Not recognizing that environment variables can contain secrets requiring masking.

#3 Trying to update environment variables defined in the 'environment' block dynamically during pipeline execution.

Wrong approach:

environment {
MY_VAR = 'initial'
}
script {
env.MY_VAR = 'changed'
}
echo "Value is ${env.MY_VAR}"

Correct approach:

Use separate variables inside script blocks or parameters for dynamic values instead of changing 'environment' block variables.

Root cause:

Assuming 'environment' block variables are mutable during pipeline runtime.

Key Takeaways

Environment variables in Jenkins are named values that provide build and environment information accessible during pipeline execution.

Accessing environment variables uses the 'env' object in pipelines, enabling dynamic and flexible automation scripts.

Custom environment variables can be defined but have scope rules; shell step variables do not persist outside their process.

Handling secrets via environment variables requires Jenkins credentials and masking to keep sensitive data safe.

Understanding environment variable scope and lifecycle prevents common pipeline bugs and improves build reliability.

Practice

1. In a Jenkins Pipeline script, how do you access an environment variable named BUILD_NUMBER?

easy

A. Using BUILD_NUMBER directly without prefix

B. Using env.BUILD_NUMBER

C. Using getEnv('BUILD_NUMBER')

D. Using $BUILD_NUMBER inside the script block

Solution

1. Step 1: Understand Jenkins environment variable access

   Jenkins Pipeline exposes environment variables via the env object.

2. Step 2: Access the variable using the correct syntax

   You access BUILD_NUMBER as env.BUILD_NUMBER in the script.

3. Final Answer:

   Using env.BUILD_NUMBER -> Option B

4. Quick Check:

   env.VARIABLE_NAME = correct access [OK]

Hint: Always prefix environment variables with env. in Jenkins [OK]

Common Mistakes:

• Trying to use variable name without env prefix
• Using shell-style $VARIABLE inside Groovy script
• Calling non-existent getEnv() method

2. Which of the following is the correct syntax to print the environment variable JOB_NAME in a Jenkins Pipeline script block?

easy

A. println("JOB_NAME")

B. echo $JOB_NAME

C. println(env.JOB_NAME)

D. print(JOB_NAME)

Solution

1. Step 1: Identify the correct way to print env variables in Groovy script

   In Jenkins Pipeline Groovy scripts, use println(env.VARIABLE) to print environment variables.

2. Step 2: Check each option

   println("JOB_NAME") prints the string "JOB_NAME" literally. echo $JOB_NAME uses shell syntax, invalid in Groovy. print(JOB_NAME) attempts to print JOB_NAME directly, but it's not available in Groovy scope without env prefix.

3. Final Answer:

   println(env.JOB_NAME) -> Option C

4. Quick Check:

   Use println(env.VARIABLE) to print env vars in script [OK]

Hint: Use println(env.VARIABLE) inside script blocks [OK]

Common Mistakes:

• Using shell syntax like $VARIABLE inside Groovy
• Printing variable name as string instead of value
• Trying to access variables without env. prefix

3. Given this Jenkins Pipeline snippet:

pipeline {
  agent any
  stages {
    stage('Print Env') {
      steps {
        script {
          echo "Branch is: ${env.BRANCH_NAME}"
        }
      }
    }
  }
}

What will be the output if the environment variable BRANCH_NAME is set to feature-123?

medium

A. Branch is: feature-123

B. Branch is: ${env.BRANCH_NAME}

C. Branch is: BRANCH_NAME

D. Error: BRANCH_NAME not found

Solution

1. Step 1: Understand string interpolation in Jenkins Pipeline

   Using double quotes with ${env.BRANCH_NAME} interpolates the variable value.

2. Step 2: Substitute the environment variable value

   Since BRANCH_NAME is set to "feature-123", the output will be "Branch is: feature-123".

3. Final Answer:

   Branch is: feature-123 -> Option A

4. Quick Check:

   Double quotes + ${env.VAR} = variable value [OK]

Hint: Use double quotes and ${env.VAR} for variable interpolation [OK]

Common Mistakes:

• Using single quotes which prevent interpolation
• Printing variable name literally without ${}
• Assuming env variables are undefined

4. You wrote this Jenkins Pipeline snippet:

pipeline {
  agent any
  environment {
    MY_VAR = 'hello'
  }
  stages {
    stage('Test') {
      steps {
        script {
          echo env.MY_VAR
        }
      }
    }
  }
}

But the output is empty. What is the likely cause?

medium

A. The environment block syntax is incorrect; use MY_VAR='hello' with quotes and no spaces around =

B. Environment variables must be accessed as env['MY_VAR'] not env.MY_VAR

C. The environment variable was not set correctly; use MY_VAR='hello' without spaces

D. You cannot access environment variables inside script blocks

Solution

1. Step 1: Check environment block syntax

   In Jenkins Pipeline, environment variables must be assigned with no spaces around = and values in quotes, like MY_VAR='hello'.

2. Step 2: Identify the syntax error in the snippet

   The snippet uses MY_VAR = 'hello' with spaces around = which is invalid and causes the variable not to be set.

3. Final Answer:

   The environment block syntax is incorrect; use MY_VAR='hello' with quotes and no spaces around = -> Option A

4. Quick Check:

   Use no spaces around = in environment block [OK]

Hint: No spaces around = in environment block assignments [OK]

Common Mistakes:

• Adding spaces around = in environment variable assignment
• Trying to access env vars incorrectly
• Assuming script block can't access env vars

5. You want to pass a secret API key stored as an environment variable API_KEY to a shell command in Jenkins Pipeline. Which is the best way to do this securely?

hard

A. Use sh "curl -H 'Authorization: Bearer $API_KEY' https://api.example.com"

B. Use sh(script: "curl -H 'Authorization: Bearer ${env.API_KEY}' https://api.example.com")

C. Use sh(script: "curl -H 'Authorization: Bearer $API_KEY' https://api.example.com", environment: [API_KEY: env.API_KEY])

D. Use Jenkins credentials binding plugin to inject API_KEY and access it as env.API_KEY inside sh

Solution

1. Step 1: Understand secure handling of secrets in Jenkins

   Secrets like API keys should be stored in Jenkins credentials and injected securely, not hardcoded or exposed in logs.

2. Step 2: Use credentials binding plugin

   This plugin injects secrets as environment variables during the build, accessible as env.API_KEY inside sh without exposing them in logs.

3. Final Answer:

   Use Jenkins credentials binding plugin to inject API_KEY and access it as env.API_KEY inside sh -> Option D

4. Quick Check:

   Use credentials plugin for secrets, not plain env vars [OK]

Hint: Use Jenkins credentials plugin for secrets, not plain env vars [OK]

Common Mistakes:

• Passing secrets directly in shell commands risking exposure
• Using string interpolation exposing secrets in logs
• Not using Jenkins credentials plugin for sensitive data