Environment variables in builds in Jenkins - Deep Dive

Overview - Environment variables in builds

What is it?

Environment variables in builds are special values set outside the code that Jenkins uses during a build process. They store information like paths, credentials, or settings that the build needs to run correctly. These variables can be predefined by Jenkins, set by users, or created dynamically during the build. They help keep builds flexible and secure without changing the actual code.

Why it matters

Without environment variables, every build would need hardcoded values, making it hard to change settings or reuse code safely. This would cause mistakes, slow down development, and risk exposing sensitive data like passwords. Environment variables let teams easily adjust builds for different projects or servers, improving speed and security in software delivery.

Where it fits

Before learning environment variables, you should understand basic Jenkins concepts like jobs and pipelines. After this, you can learn about Jenkins credentials management and pipeline scripting to handle secrets and complex build logic. This topic fits in the middle of mastering Jenkins automation.

Mental Model

Core Idea

Environment variables are like adjustable labels that Jenkins attaches to a build, providing flexible information the build can use without changing its code.

Think of it like...

Imagine baking cookies using a recipe card. Instead of writing the oven temperature on the card, you use a sticky note that you can change anytime. This sticky note is like an environment variable—easy to update without rewriting the recipe.

┌─────────────────────────────┐
│ Jenkins Build Process        │
│                             │
│  ┌───────────────────────┐  │
│  │ Environment Variables │  │
│  │  - PATH               │  │
│  │  - BUILD_NUMBER       │  │
│  │  - CUSTOM_SETTING     │  │
│  └───────────────────────┘  │
│          │                  │
│          ▼                  │
│  Build uses these values    │
│  to run commands and tests  │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What are environment variables

Concept: Introduce the basic idea of environment variables as named values accessible during a build.

Environment variables are like small pieces of information stored outside your code. Jenkins sets some automatically, like BUILD_NUMBER which tells you the current build count. You can also add your own variables to customize builds. They help your build scripts know things like where to find tools or what version to build.

Result

You understand that environment variables hold data Jenkins and your build scripts can use to behave differently without changing code.

Knowing environment variables exist outside code helps you separate configuration from logic, making builds easier to manage and change.

2

Foundation

How Jenkins provides environment variables

Concept: Explain Jenkins built-in environment variables and how they are available in builds.

Jenkins automatically sets many environment variables for every build. Examples include: - BUILD_NUMBER: The current build's number - JOB_NAME: The name of the job - WORKSPACE: The folder where the build runs You can see these variables in build logs or use them in scripts by referencing their names, like $BUILD_NUMBER in shell scripts.

Result

You can access Jenkins default environment variables in your build scripts to get useful build info.

Understanding built-in variables lets you write scripts that adapt to the build context without extra setup.

3

Intermediate

Setting custom environment variables

🤔Before reading on: do you think you can set environment variables only globally or also per build? Commit to your answer.

Concept: Show how to define your own environment variables for specific builds or jobs.

You can add custom environment variables in Jenkins in several ways: - In the job configuration under 'Build Environment' using 'Inject environment variables' - Directly in pipeline scripts using 'environment' block - Passing variables from parameters Example in a pipeline: pipeline { environment { GREETING = 'Hello' } stages { stage('Example') { steps { echo "${GREETING}, Jenkins!" } } } } This prints 'Hello, Jenkins!' during the build.

Result

You can customize builds by adding your own variables that scripts can use.

Knowing how to set custom variables empowers you to make builds flexible and reusable across different scenarios.

4

Intermediate

Using environment variables in pipeline scripts

🤔Before reading on: do you think environment variables in Jenkins pipelines are accessed the same way as in shell scripts? Commit to your answer.

Concept: Teach how to read and use environment variables inside Jenkins pipeline code.

In Jenkins pipelines, environment variables are accessed via the 'env' object. For example: pipeline { environment { MY_VAR = '123' } stages { stage('Print') { steps { script { echo "Value is ${env.MY_VAR}" } } } } } This prints 'Value is 123'. Note that in shell steps you use $MY_VAR, but in Groovy scripts you use env.MY_VAR.

Result

You can correctly access environment variables in different parts of pipeline scripts.

Understanding the difference in syntax between shell and Groovy contexts prevents common bugs when using variables.

5

Intermediate

Passing environment variables between build steps

Concept: Explain how environment variables persist or change across different build steps.

Environment variables set at the start of a build are available in all steps. However, if you set a variable inside a shell step, it does not automatically persist to the next step because each shell runs in its own process. To share variables between steps, you can: - Use Jenkins environment variables set in the pipeline - Write variables to files and read them later - Use the 'withEnv' step to temporarily set variables Example: steps { withEnv(['MY_VAR=hello']) { sh 'echo $MY_VAR' } } This ensures MY_VAR is available in the shell step.

Result

You know how to manage variable scope and persistence across build steps.

Knowing variable scope helps avoid confusion when variables seem missing between steps.

6

Advanced

Securing sensitive environment variables

🤔Before reading on: do you think storing passwords as plain environment variables is safe? Commit to your answer.

Concept: Introduce Jenkins credentials and how to inject them as environment variables securely.

Storing secrets like passwords directly as environment variables is risky because they can appear in logs or be exposed. Jenkins provides a Credentials plugin to store secrets safely. You can inject credentials into builds as environment variables without exposing them: pipeline { environment { SECRET = credentials('my-secret-id') } stages { stage('Use Secret') { steps { sh 'echo Using secret in build' } } } } This way, the secret is masked in logs and handled securely.

Result

You can safely use sensitive data in builds without risking exposure.

Understanding secure handling of secrets prevents serious security leaks in production.

7

Expert

Dynamic environment variables and build optimization

🤔Before reading on: do you think environment variables can be changed during a build and affect later stages? Commit to your answer.

Concept: Explore how environment variables can be dynamically set or modified during builds and how this affects build flow and caching.

In complex pipelines, environment variables can be set or updated dynamically using scripts or plugins. For example, you might run a script that detects the version of a tool and sets an environment variable accordingly. However, changes to environment variables in one step do not automatically propagate to others unless explicitly passed. Also, environment variables can influence build caching and conditional execution. For example, changing a variable might skip or trigger certain stages. Example snippet: script { env.DYNAMIC_VAR = sh(script: 'detect_version.sh', returnStdout: true).trim() } This sets DYNAMIC_VAR dynamically for later use.

Result

You can create smarter builds that adapt during execution and optimize resource use.

Knowing how to dynamically control environment variables unlocks advanced build customization and efficiency.

Under the Hood

Jenkins sets environment variables by injecting them into the shell or process environment where build steps run. Each build step runs in its own process, inheriting environment variables from Jenkins or the pipeline context. Variables set inside a shell step affect only that process unless explicitly passed or stored externally. Jenkins pipeline scripts access variables via a Groovy 'env' map that reflects the current environment state. Credentials are injected securely by Jenkins agents using plugins that mask and protect secret values.

Why designed this way?

This design separates configuration from code, allowing builds to be flexible and reusable. Running steps in separate processes isolates them for safety and stability but requires explicit variable passing. Secure credential injection was added to prevent accidental leaks of sensitive data, a common problem in early CI systems. The pipeline 'env' object provides a unified way to access variables across different script contexts.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Jenkins Master│──────▶│ Build Agent   │──────▶│ Build Step 1  │
│ (sets env)    │       │ (injects env) │       │ (shell process)│
└───────────────┘       └───────────────┘       └───────────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ Build Step 2    │
                          │ (new shell proc)│
                          └─────────────────┘

Note: Each build step runs in its own process with environment variables passed from Jenkins or pipeline.

Myth Busters - 4 Common Misconceptions

Quick: If you set an environment variable inside a shell step, will it be available in the next shell step? Commit to yes or no.

Common Belief: Setting an environment variable in one shell step makes it available in all following steps automatically.

Reality: Each shell step runs in a separate process, so environment variables set inside one step do not persist to the next unless explicitly passed or stored externally.

Why it matters: Assuming variables persist causes build failures or unexpected behavior when later steps can't access needed data.

Quick: Is it safe to store passwords as plain environment variables in Jenkins builds? Commit to yes or no.

Common Belief: Storing secrets as plain environment variables is fine because builds are private.

Reality: Plain environment variables can be exposed in logs or process lists, risking secret leaks. Jenkins credentials plugin must be used for secure secret handling.

Why it matters: Ignoring this leads to serious security breaches and compromised systems.

Quick: Do Jenkins environment variables always have the same names and values across all jobs? Commit to yes or no.

Common Belief: Jenkins environment variables are consistent and identical for every job and build.

Reality: Some variables are job-specific or build-specific, like BUILD_NUMBER or JOB_NAME, and their values change per build or job.

Why it matters: Assuming variables are static can cause scripts to behave incorrectly or use wrong data.

Quick: Can you access environment variables in Jenkins pipeline scripts the same way as in shell scripts? Commit to yes or no.

Common Belief: You can use $VAR syntax in Jenkins pipeline Groovy scripts just like in shell scripts.

Reality: In Groovy pipeline scripts, environment variables must be accessed via env.VAR, not $VAR syntax.

Why it matters: Using wrong syntax causes errors or empty values, breaking pipelines.

Expert Zone

1

Jenkins environment variables set in the pipeline 'environment' block are immutable during the build unless explicitly overridden in script blocks.

2

Credentials injected as environment variables are masked in logs but can still be exposed if printed explicitly, so careful scripting is required.

3

Plugins or external scripts can modify environment variables dynamically, but this can cause unpredictable build behavior if not managed carefully.

When NOT to use

Avoid relying solely on environment variables for complex data passing between build steps; use Jenkins artifacts, files, or pipeline parameters instead. For secret management, prefer Jenkins credentials or external vaults rather than plain environment variables. In distributed builds, environment variables might not propagate as expected, so use shared storage or Jenkins features designed for multi-node coordination.

Production Patterns

In production Jenkins pipelines, environment variables are used to configure build parameters, select deployment targets, and inject secrets securely. Teams often combine environment variables with parameterized builds to create reusable pipelines. Dynamic environment variables help optimize builds by conditionally running stages or caching dependencies based on detected environment states.

Connections

Docker environment variables

Similar pattern of passing configuration data to running processes

Understanding Jenkins environment variables helps grasp how Docker containers receive configuration, enabling consistent behavior across environments.

Unix shell environment

Builds on the same operating system concept of environment variables

Knowing how environment variables work in Unix shells clarifies their behavior in Jenkins build steps and why scope matters.

Secure secret management in cybersecurity

Builds on principles of protecting sensitive data in systems

Recognizing the risks of exposing secrets in environment variables connects Jenkins practices to broader cybersecurity best practices.

Common Pitfalls

#1 Setting environment variables inside a shell step and expecting them in the next step.

Wrong approach:

sh 'export MY_VAR=hello'
sh 'echo $MY_VAR' # This will print nothing

Correct approach:

withEnv(['MY_VAR=hello']) {
sh 'echo $MY_VAR' # This prints 'hello'
}

Root cause:

Misunderstanding that each shell step runs in a separate process with its own environment.

#2 Storing passwords as plain environment variables in Jenkins jobs.

Wrong approach:

environment {
PASSWORD = 'mypassword'
}
sh 'echo $PASSWORD' # Password exposed in logs

Correct approach:

environment {
PASSWORD = credentials('password-id')
}
sh 'use password securely without echoing'

Root cause:

Lack of awareness about Jenkins credentials plugin and security risks.

#3 Accessing environment variables in pipeline Groovy scripts using shell syntax.

Wrong approach:

echo "$MY_VAR" # In Groovy script, this prints literal string or empty

Correct approach:

echo "${env.MY_VAR}" # Correct Groovy syntax to access env variables

Root cause:

Confusing shell variable syntax with Groovy pipeline syntax.

Key Takeaways

Environment variables provide a flexible way to pass configuration and data to Jenkins builds without changing code.

Jenkins sets many useful built-in environment variables automatically, and you can add your own for customization.

Each build step runs in its own process, so environment variables set inside one shell step do not persist to others unless managed carefully.

Secure handling of sensitive data requires using Jenkins credentials rather than plain environment variables to avoid leaks.

Advanced pipelines use dynamic environment variables to adapt build behavior and optimize execution.