An environment variable is a named piece of text that a running program can look up by its name.

Let us build the idea from the ground up. A variable is a name attached to a value, like a label stuck on a jar. The label says “sugar”, and the jar holds the sugar. You can change what is inside the jar without changing the label. An environment is the set of surroundings a program runs in. So an environment variable is a labelled value that lives in the surroundings of a program, where the program can read it whenever it wants.

Every computer already has them. The variable PATH tells your terminal where to look for programs. The variable HOME names your personal folder. Programs read these quietly without asking you. Jenkins uses the same well-known mechanism: before it runs a step, it places a set of variables in the surroundings of that step. Your commands, scripts and tools can then read them by name.

Two facts are worth remembering right away. First, every environment variable is text. Even a number such as a build number is stored as a piece of text, and the program that reads it must convert it if it needs arithmetic. Second, environment variables are looked up at the moment of use, so changing one changes the behaviour of every step that reads it, without editing those steps.

They keep jobs flexible, tidy and safe. Without them, every value would be typed directly into every step.

Imagine a build that deploys to a test server. Without variables, the server address is typed into ten different steps. When the address changes, you must find and fix all ten, and you will surely miss one. With a variable, the address lives in one place, and all ten steps read it. Change it once, and everything follows.

Before you create anything, Jenkins already places many useful variables in every build.

Variables added by plugins

Plugins add their own variables. The Git plugin, for example, adds names for the commit being built, the branch and the repository address, typically GIT_COMMIT, GIT_BRANCH and GIT_URL. Multibranch Pipelines add BRANCH_NAME for the branch being built, and for pull requests they add names such as CHANGE_ID and CHANGE_TARGET. These let a Pipeline behave differently for a feature branch than for the main branch, or for a pull request than for a release.

A short look at the journey explains why scope and syntax matter so much.

A step often runs on an agent, a worker machine, while the Pipeline is managed by the controller, the brain of Jenkins. When a step starts, Jenkins gathers the variables that apply, places them in the surroundings of the step process, and then starts your command. The command reads them using the syntax of whatever language it uses.

flowchart TD
    A["Operating system variables of the agent"] --> M["Jenkins merges all layers"]
    B["Global and node settings in Jenkins"] --> M
    C["Built-in build variables"] --> M
    D["Pipeline level and stage level definitions"] --> M
    E["Parameters chosen for this build"] --> M
    F["Bound credentials for a block"] --> M
    M --> S["Environment placed around the step process"]
    S --> R["Your command reads the values by name"]
    

You can create variables at several levels, from the whole server down to a single block of steps.

Global and node-level variables

An administrator can define variables for the whole Jenkins server in the system settings, under an area for global properties. Each agent machine can also carry its own variables in its configuration. Global values are shared by every build. Node values apply only to builds that land on that machine, which is handy when the same tool sits in different folders on different agents.

Freestyle projects

In a Freestyle project, the Build Environment section and parameter settings are the main places. Ticking “This project is parameterized” turns each parameter into an environment variable for the build. Some plugins add options in the Build Environment section for injecting more variables from a file or a list. Use such injection plugins with care and read their security notes, because they can widen who is able to affect a build’s surroundings.

Declarative Pipelines

In a Declarative Pipeline, you use a section named environment. Placed at the top level, it makes the variables available to every stage. Placed inside a stage, it makes them available only to that stage. Each entry is a name and a value, in the form NAME = 'value', and later entries can even use earlier ones. This is the tidiest and most popular way to define variables for a Pipeline.

Wrapper steps and scripts

The withEnv step is a wrapper. It takes a list of name and value pairs and applies them only to the steps inside its block. When the block ends, the variables vanish. In scripted code, you can also assign to the special env object, for example env.RELEASE_TYPE = 'beta', and later steps of the same build will see that value. This is useful when a value is calculated during the build.

When the same name is defined in more than one place, Jenkins needs a rule for choosing.

Scope means the area in which a variable is visible. A stage-level variable is visible only inside its stage. A Pipeline-level one is visible everywhere in that Pipeline. A wrapper block gives visibility only inside the block.

The general principle is that the closest definition wins. If a Pipeline defines a variable and one stage defines the same name differently, the steps in that stage see the stage’s value, while the other stages still see the Pipeline’s value. A wrapper block placed inside a stage overrides both, for its steps only.

flowchart TD
    G["Global or node value: REGION is eu"] --> P["Pipeline level: REGION is us"]
    P --> S1["Stage Build: no override, sees us"]
    P --> S2["Stage Deploy: sets REGION to ap"]
    S2 --> W["Inside a wrapper block: REGION is set to sa"]
    W --> V1["Steps inside the block see sa"]
    S2 --> V2["Other Deploy steps see ap"]
    S1 --> V3["Build steps see us"]
    

The same variable is read in different ways, depending on where the reading happens. This is the single biggest source of beginner confusion.

Who fills in the value: Jenkins or the shell?

This detail deserves a slow explanation. In Pipeline files, text in double quotes is processed by Jenkins first: any ${...} placeholders are replaced with values before the command is even sent to the machine. Text in single quotes is passed exactly as written, and the shell on the machine fills in variables when the command runs. Both work for ordinary values, but they behave differently, and the difference matters greatly for secrets, as we will see next.

sequenceDiagram
    participant P as Pipeline code
    participant J as Jenkins engine
    participant SH as Shell on the agent
    Note over P,SH: Double quotes
    P->>J: Text with a placeholder in double quotes
    J->>J: Replace the placeholder with the value
    J->>SH: Send the finished command with the value inside
    Note over P,SH: Single quotes
    P->>J: Text with a variable in single quotes
    J->>SH: Send the command exactly as written
    SH->>SH: Look up the variable in its own environment
    

Variables are a convenient way to hand secrets to a step, but only if it is done through the right door.

A secret is a value that must not be seen by everyone: a password, a token or a private key. Jenkins keeps secrets in its credentials store, a protected vault. A plain environment variable is not a vault. Anyone who can read the Pipeline file or the console output can read it. So secrets must come from the credentials store, and be bound into a variable only for the moment they are needed.

flowchart LR
    V["Credentials store: protected vault"] -->|bind for a block| E["Environment variable exists only during the block"]
    E --> S["Step reads the variable from its environment"]
    S --> M["Jenkins masks the value if it appears in the log"]
    E -->|block ends| X["Variable disappears"]
    

Masking, and its limits

When a secret is bound through the credentials system, Jenkins remembers its value and replaces it with stars if it shows up in the console output. This is a valuable safety net, but it is not perfect. A secret that is changed, encoded, split into pieces or embedded in a longer text may slip through unmasked. And secrets that Jenkins never knew were secrets, such as a password typed directly into a script or a plain variable, are not masked at all.

Habits that keep secrets safe

• Never type secrets into environment sections or scripts. Reference the credentials store instead.
• Bind as narrowly as possible. Use a wrapper block around only the steps that need the secret.
• Never print all variables. A command that lists the whole environment can reveal secrets that were not masked.
• Turn off command echoing near secrets. Shell steps normally print each command, so keep secret handling in scripts that do not echo them.
• Assume anything in a log is visible to your whole team. Logs are stored, shipped and pasted into chats.
• Rotate anything that leaks. Replace the secret immediately.

Three ideas are often confused. Knowing the difference tells you which one to pick.

flowchart TD
    N["I need a value in my build"] --> Q1{"Is it secret?"}
    Q1 -->|Yes| C["Use the credentials store and bind it"]
    Q1 -->|No| Q2{"Does it change with each run?"}
    Q2 -->|Yes| P["Use a build parameter"]
    Q2 -->|No| Q3{"Is it shared by many jobs?"}
    Q3 -->|Yes| G["Use a global or node level variable"]
    Q3 -->|No| E["Use a Pipeline or stage environment section"]
    

A parameter is like a question Jenkins asks before the build starts, such as “Which version should I build?” Once answered, its value is also made available as an environment variable, so your shell steps can read it by name, and Pipeline code can read it through the params object. So parameters and environment variables work together: parameters are one way that values arrive, and environment variables are one way they are read.

Variables can carry information from one part of a build to another, but you must use the right method.

Sometimes a step discovers a fact that later steps need, such as a version number read from a file, or the name of a newly created resource. There are two common ways to pass it on.

Two limits are worth knowing. First, a variable set by a shell command using the shell’s own syntax lives only inside that one shell process. When the step ends, the process ends, and the value is gone. The next step starts a fresh shell that knows nothing about it. This surprises nearly everyone at first. To keep a value, hand it back to Jenkins as a return value, then place it on the env object.

Second, the variables set inside a withEnv block or a stage environment section do not survive beyond their scope. Design each stage so that it does not depend on hidden leftovers from an earlier one.

sequenceDiagram
    participant S1 as Step 1 shell process
    participant J as Jenkins env object
    participant S2 as Step 2 shell process
    S1->>S1: Set a variable using shell syntax
    Note over S1: Value exists only inside this process
    S1-->>J: Process ends, the value is lost
    J->>S2: Start a new shell with the Jenkins environment
    S2->>S2: The shell variable from step 1 is not there
    Note over J,S2: To keep a value, return it to Jenkins and store it on the env object
    

The place where a step runs changes what it sees. This matters more as your setup grows.

Different agents, different surroundings

Each agent has its own operating system variables. A tool folder that exists on one machine may be missing from another, and the search path may differ. Variables from Jenkins itself, such as the build number, are the same everywhere, but machine facts differ. This is why a build can work on one agent and fail on another: a variable the step relied on is set differently on each.

Containers

When a step runs inside a container, the container has its own separate environment. Jenkins passes along some of its build variables, but the container’s own variables come from its image and settings. Treat a container as a fresh room: anything the tools inside need must be provided explicitly. In return, containers give you a big benefit, because every run starts from exactly the same surroundings.

Parallel branches

When stages run in parallel, each branch may run on a different agent, with its own surroundings. Variables defined at the Pipeline level are visible to all of them. But values assigned during the build by one branch are not a safe way to pass information to another branch, because their timing is unpredictable. Give each branch its own variables, and gather results at the end.

Environment variables are simple and useful, and they come with a few costs.

The main trade-off is convenience versus clarity. Variables make a Pipeline flexible, but every extra layer makes it harder to see what a step will actually receive. Aim for a small number of well-named variables, defined in as few places as possible.

Most variable problems are of the same few kinds. Recognise the symptom, and the fix is usually short.

A pattern is a proven habit. An anti-pattern is a tempting shortcut that causes trouble later.

Patterns worth copying

Anti-patterns to avoid

A few steady habits keep your variables tidy, predictable and safe.

Best practices

• Use clear, unique names. Capital letters with underscores are the common convention.
• Define each variable in one place. Avoid the same name at several levels.
• Keep secrets in the credentials store. Bind them narrowly and mask them.
• Prefer single quotes for shell commands. Let the shell read variables from its environment.
• Use parameters for run-time choices. Use environment sections for fixed settings.
• Validate required values early. Fail with a friendly message rather than a mysterious error later.
• Document each variable. A short comment explains purpose and expected format.
• Remember values are text. Convert before comparing or calculating.
• Print selectively. Never dump the whole environment into a log.
• Keep the Jenkinsfile in version control. Changes to variables are then reviewed like any other change.

Common mistakes

Here is how teams use environment variables in everyday delivery work.

Environment variables are the shared whiteboard of a Jenkins build: labelled pieces of text that any step can read by name. Jenkins fills the board with useful facts, such as the build number, the workspace and the branch, and lets you add your own at the level of the server, the machine, the job, the stage or a single block of steps.

Using them well comes down to a few clear habits. Choose unique, descriptive names and define each one in a single place. Remember that values are text, that scope decides visibility, and that the closest definition wins. Use the right syntax for the place where you read the value, and prefer single quotes in shell commands. Keep secrets in the credentials store and bind them narrowly. With those habits, variables make your Pipelines flexible, portable and safe.