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.