Start here. In this chapter you learn what the environment block is, where it lives, and why it exists, using words a beginner can follow.

Jenkins is a tool that automates the boring, repeatable parts of building software. It fetches your code, compiles it, runs tests, packages it, and can push it to a server. You describe those jobs in a text file called a Jenkinsfile. That file holds a pipeline, which is simply an ordered list of work to do.

An environment variable is a named value that is handed to a program when it starts. The name is written in capital letters by tradition, such as APP_NAME or DEPLOY_REGION. The program reads the name and gets the value. Your operating system already does this: the variable PATH tells your computer where to look for programs.

The environment block (its official name is the environment directive) is the part of a Declarative Pipeline where you declare these named values. Everything you declare there becomes available to the steps of your pipeline, and to any shell command those steps launch. In one sentence: the environment block is where a Jenkins pipeline keeps its named settings.

The three jobs it does

Before we look at Jenkins syntax, it helps to understand the problem that environment variables solve, because that problem is older than Jenkins itself.

A short history

In the early days of software, programmers often wrote settings straight into the program. A database address, a port number, or a password sat inside the source code. This worked until the same program had to run in two places. The developer’s laptop, the testing server, and the live production server all need different database addresses. Editing the code for each place is slow and risky, because every edit is a chance to break something or to accidentally commit a secret.

Unix systems solved a piece of this long ago with environment variables, which are values held outside the program and given to it when it starts. Around 2011, engineers at Heroku wrote down a set of habits called The Twelve-Factor App. One of its rules says that configuration, meaning anything that changes between deployments, should live in the environment and not in the code. The idea spread widely. Today, containers, cloud platforms, and build tools all lean on it.

Jenkins itself began in 2011 as a fork of a project called Hudson. Jenkins pipelines arrived later as the Pipeline plugin, which became a built-in part of the product with Jenkins 2.0 in 2016. The Declarative Pipeline syntax, the one with the tidy environment directive, followed shortly after and reached its first stable release in early 2017. So the environment block is a fairly young feature that sits on a very old idea.

The problem in a build system

A build system has an extra reason to care. The same Jenkinsfile is used again and again, by many branches, on many machines, at many times of day. What changes each time is the data around it: the commit number, the branch name, the target environment. If each of those values were baked into the Jenkinsfile, you would need a different Jenkinsfile for every situation. Environment variables let one file stay the same while the values flowing through it change.

A few Jenkins words come up in every later chapter. Learn them here once, and the rest of the guide reads easily.

Declarative versus Scripted

Jenkins supports two writing styles for pipelines. Declarative has a fixed, tidy shape. You fill in labelled sections such as agent, environment, stages, and post. It is easier to read and it checks your file for mistakes before running. Scripted is more free-form. It is real Groovy programming, which gives you more power and also more ways to make a mess. Most teams today start with Declarative and use small script sections only when they must.

The environment block is a Declarative section. That is why you will see it near the top of well-organised Jenkinsfiles, right after the agent choice and before the stages.

How a run begins

When a build starts, the controller reads your Jenkinsfile, works out the plan, and hands each stage to an agent. Along the way it prepares a bundle of information about the run: the build number, the job name, the branch, and more. That bundle becomes the starting set of environment variables. Whatever you write in your own environment block is added on top of it.

Now we look at the shape of the block itself: where it may be placed, what goes inside, and the rules Jenkins follows when it reads it.

The basic shape

The block has a very simple form. The word environment is followed by a pair of curly braces. Inside the braces, each line has a name, an equals sign, and a value. The name is what your commands will read. The value is text, and it is usually written inside quotation marks. Nothing else is required. There are no commas between lines and no special ending.

Names follow the usual convention: capital letters, digits, and underscores, with a letter or underscore at the start. A name like APP_VERSION is good. A name with spaces or dashes causes trouble in shells, so avoid them.

Two places it can live

You may place the block in two positions, and the position decides who can see the values.

What a value can be

Every value in the block ends up as text. Even if you write a number or the word true, Jenkins stores it as a string. This surprises people and is the source of a famous mistake we cover in the mistakes chapter. A value may be a fixed piece of text, a reference to another variable, the result of a small expression, or a call to the credentials helper.

The reading order, step by step

Jenkins hands you a set of ready-made variables for free. Knowing them saves you from inventing your own for facts Jenkins already knows.

Before your own block adds anything, every run already carries information about itself. These are called built-in or predefined variables. You can read them in your steps and also use them inside your own environment block to build new values. Which ones exist depends slightly on your job type and plugins, so treat the table below as the common core and check your own Jenkins for the complete list. Jenkins publishes the live list on a help page of your own server, under the pipeline syntax reference.

Combining them into your own values

A very common habit is to build a new variable from built-in ones. For example, a team may define an image tag by joining the branch name and the build number, so every container image can be traced to the exact run that produced it. Because the block is read top to bottom, you can define a base name first and then use it in the lines below.

When the same name is defined in more than one place, which value does a step actually see? This chapter answers that, and explains where each place fits.

Where a variable can come from

A value can arrive from several layers, moving from the most general to the most specific.

• The agent’s own operating system. Every machine already has variables such as PATH and HOME.
• Global properties on the controller. An administrator can define variables in Jenkins’ system settings that apply to every job.
• Node properties. An administrator can define variables on one specific agent.
• Built-in Jenkins variables. The ones from the previous chapter.
• Job parameters. Values a person chooses when they press the build button. Parameters are also exposed as environment variables.
• The pipeline-level environment block.
• The stage-level environment block.
• The withEnv step. A step that sets variables for just the steps wrapped inside it.

flowchart TD
  A["Agent operating system variables"] --> B["Global properties on the controller"]
  B --> C["Node properties on the agent"]
  C --> D["Built in Jenkins variables"]
  D --> E["Pipeline level environment block"]
  E --> F["Stage level environment block"]
  F --> G["withEnv step wrapping some steps"]
  G --> H["Shell process started by an sh or bat step"]
    

The diagram shows the general idea: as you move down, the layers become more specific and closer to the command that runs. In everyday use, the more specific place wins. A stage-level definition beats a pipeline-level definition with the same name, and withEnv beats both for the steps inside it. Exact ordering between the administrator-defined layers and the built-in ones can vary with plugins and versions, so when in doubt, print the variables and look, which we show in the troubleshooting chapter.

How long a value lives

Scope is about place, and lifetime is about time. A pipeline-level value lives for the whole run. A stage-level value lives only while that stage runs. A withEnv value lives only inside its wrapped steps. Once you leave, the value is gone, and a later stage that reads the same name will see either the wider value or nothing.

Reading parameters and environment together

Parameters deserve one extra note. When you define a build parameter, Jenkins gives you two ways to read it: through a dedicated object for parameters, and through the environment. The dedicated object keeps the true type, so a yes-or-no parameter stays a real yes-or-no. The environment version turns everything into text. When you can, read the parameter object for decisions and use the environment version only for passing values to shell commands.

This chapter lifts the lid. Understanding what Jenkins does behind the scenes explains almost every strange behaviour you will ever meet.

Two worlds: Groovy and the shell

A Jenkins pipeline lives in two different worlds at the same time, and the environment block sits at the border between them.

The first world is Groovy, running on the controller. This is where Jenkins reads your Jenkinsfile, decides what to run, and keeps track of progress. Here, the variables live inside an object named env. You can read a value as env.NAME in pipeline expressions.

The second world is the shell (or batch, or PowerShell) running on the agent. This is a completely separate program, started fresh by a step such as sh. The shell does not know anything about Groovy. It only knows the environment variables that were placed into its process when it started.

The important job of the environment block is to make sure the two worlds agree. When a step launches a shell, Jenkins takes the current set of environment values and places them into the new process, so the shell can read them the normal Unix way.

Why the quotation marks matter

Because there are two worlds, a dollar sign followed by a name can be understood by either one. This is the single most important internal detail in the topic.

In Groovy, text inside double quotation marks is processed by Groovy first. If it contains a dollar sign and a name, Groovy replaces it with the value on the controller before the command is even sent to the agent. The shell receives finished text with the value already pasted in.

Text inside single quotation marks is left alone by Groovy. The shell receives the dollar sign and name as they are, and the shell itself looks up the value from its environment at run time.

Both can produce the same visible result, but they are different mechanisms with different consequences. For ordinary values the difference is invisible. For secrets it is critical, and we return to it in the credentials and security chapters.

The environment is copied, not shared

When a shell starts, it receives a copy of the variables. If that shell changes a variable, the change lives and dies inside that shell. It does not travel back to Jenkins, and the next step will not see it. Many newcomers write a command that sets a variable in one step and expect a later step to find it, and are puzzled when it is empty. Each step that launches a shell gets a fresh copy from Jenkins.

To carry a value forward, you must set it on the Jenkins side, in the Groovy world, for example by assigning to the env object inside a script section, or by capturing the output of a command into a variable. Then the next shell will receive it in its copy.

Steps that survive restarts

Jenkins Pipelines are designed to survive a controller restart in the middle of a run. To do this, Jenkins saves the state of the pipeline to disk as it goes, including the environment values. This design is why some clever Groovy tricks that store unusual objects in variables fail with errors about things that cannot be saved. Sticking to plain text values in the environment block keeps you safely inside what Jenkins can save and restore.

So far we have used fixed text. This chapter shows how a value can be calculated, and the rules about the order in which lines are worked out.

Referring to earlier lines

Because Jenkins reads the block from top to bottom, a line may use a variable defined above it. A team might define a registry address first and then use it inside an image name in the next line. The rule is simple: a line can only use what already exists. A line cannot use a variable defined lower in the same block, because when Jenkins reaches the earlier line, the later one has not been created yet.

Values calculated by a command

A value can also be the output of a small shell command. Jenkins runs the command when the block is read, captures what it prints, and stores that text as the value. Teams use this to compute things such as a short version of the commit id, today’s date in a fixed format, or the current version number read from a file.

There are three things to remember about this power.

1. Timing. The command runs when the block is evaluated, not when a later step uses the value. A pipeline-level value is worked out once at the start. If the underlying fact changes mid-run, the stored value will not change.
2. Location. The command runs on an agent, so an agent must exist at that moment. Stage-level blocks are a natural home for these calculations because the stage already has its agent.
3. Trailing whitespace. Command output usually ends with a newline character. Trim it so your value is clean, or your image tag might contain an invisible line break and fail in strange ways.

Changing values during the run

The environment block is for values you know at the start of a pipeline or stage. If you discover a value halfway through, such as the address of a server that a stage just created, you set it from a script section by assigning to the environment object. Values set this way stay available to the stages that follow. This is the standard way to pass small pieces of information forward from stage to stage.

Passwords, tokens, and keys should never be typed into a Jenkinsfile. The environment block offers a special helper that fetches them safely at run time.

The problem

Your pipeline often needs to prove who it is. To push an image to a registry, it needs a registry login. To call a cloud service, it needs a token. If you write those secrets into the Jenkinsfile, they are stored in Git forever, copied to every developer laptop, and visible to anyone who can read the repository. Even deleting them later does not remove them from history.

The solution: the credentials store and the credentials helper

Jenkins has a protected place called the credentials store. An administrator or an authorised user adds a secret there once, and gives it a short label called a credential ID. The Jenkinsfile then mentions only that label. Inside the environment block, a special helper named credentials() takes the label and, at run time, delivers the secret into the variable you named. The secret itself never appears in the file.

What ends up in the variables

The shape of what you receive depends on the type of credential you stored.

Jenkins documents these behaviours in its handling-credentials guide, and details can vary by plugin version, so confirm against your own installation before you rely on an unusual type.

Where the safety net has holes

Masking works by searching the log for the exact secret text. If your command changes the secret before printing it, for example by encoding it, cutting it in half, or spacing out the letters, the changed version is not recognised and shows in plain view. Masking also cannot protect anything a program sends outside Jenkins. A script that posts its environment to an outside web address has already leaked the secret before any log is written.

Jenkins gives you several tools for supplying values. Choosing the right one keeps your pipeline honest and easy to change.

The environment block is one of several mechanisms. Each has a purpose. The table below compares them side by side so you can choose deliberately.

A simple decision guide

Let us follow one real build from the moment a developer saves code to the moment a shell command reads a variable.

sequenceDiagram
  participant Dev as Developer
  participant Git as Git Repository
  participant Ctl as Jenkins Controller
  participant Agt as Jenkins Agent
  participant Sh as Shell Process
  Dev->>Git: Push a commit
  Git->>Ctl: Webhook tells Jenkins about the change
  Ctl->>Ctl: Read the Jenkinsfile and start the build
  Ctl->>Ctl: Create built in variables and read the environment block
  Ctl->>Agt: Assign the stage to an agent
  Agt->>Ctl: Ask for the credential values needed
  Ctl-->>Agt: Send the secrets for this build only
  Agt->>Sh: Start a shell with the variables placed inside
  Sh-->>Ctl: Return the exit code and log lines
    

Walking through the figure

The trigger. A developer pushes a commit. The Git server sends a small message, called a webhook, to Jenkins saying that something changed. Jenkins starts a new run.

The plan. The controller reads the Jenkinsfile from the repository. It creates the built-in variables for this run, then reads the pipeline-level environment block line by line and stores the results.

The hand-off. The controller picks an agent for the first stage. If the stage has its own environment block, it is read now. If the block asks for a credential, the agent asks the controller for it, and the controller sends the secret for this build only.

The execution. A step launches a shell. Jenkins places the combined variables into the shell’s environment. The shell runs your command, reads the variables, and sends back its output and exit code.

The clean-up. When the stage ends, stage-level values are dropped. Temporary secret files are deleted. The next stage starts with the pipeline-level values again.

Post actions and the environment

A pipeline can also have a post section that runs at the end, whether the build passed or failed. Pipeline-level values are available there, which makes the block a good home for facts such as the notification channel or the report folder. Stage-level values from a finished stage are no longer in scope, so anything the post section needs should be defined at pipeline level.

The environment block is powerful, and anything powerful can be misused. These are the practical security ideas every user should hold in mind.

Who can read a process environment?

Environment variables are visible to the program that owns them and, on many systems, to other processes running as the same user on the same machine. On a shared agent, another job that runs as the same operating system user could in principle read what your job holds. This is one strong reason to use dedicated, single-purpose agents, or short-lived container agents, for sensitive work.

Common ways secrets escape

Habits that protect you

• Least privilege. Give each credential only the permissions its pipeline needs. A deploy token for a test environment should not open production.
• Scope by folder or team. Store credentials at the narrowest level that works, so unrelated teams cannot use them.
• Single quotes for secret-using commands. Let the shell read the value itself.
• Never print secrets. Not even to check them. Print a fingerprint or the length if you must verify something.
• Rotate regularly. Change secrets on a schedule and immediately after any suspicion of exposure.
• Review Jenkinsfile changes. Treat edits to the pipeline file with the same care as edits to production code, because they can reach your secrets.
• Keep Jenkins updated. Jenkins and its plugins publish security advisories frequently, and staying current closes known holes.

Sooner or later a variable will be empty, wrong, or missing. Here is how to observe what Jenkins is doing and find the cause calmly.

Tools you already have

A calm way to debug

flowchart TD
  A["A variable is empty or wrong"] --> B{"Did you print the environment in the same stage"}
  B -->|No| C["Add a temporary print step and rerun"]
  B -->|Yes| D{"Is it defined at the right level"}
  D -->|No| E["Move it to pipeline level or the correct stage"]
  D -->|Yes| F{"Which quotation marks wrap the command"}
  F -->|Double| G["Groovy replaced it early so check the controller side value"]
  F -->|Single| H["The shell replaced it so check the shell type and spelling"]
    

The usual suspects

Metrics worth watching

The environment block does not have its own dashboard, but a few habits give you useful signals. Track how often builds fail in the first few seconds, because missing-variable failures usually happen early. Watch for warnings about insecure secret interpolation in build logs, and count them over time. Notice if the time taken to evaluate the top of the pipeline grows, which can hint that a calculated value has become slow.

Patterns are habits that have worked for many teams. Anti-patterns are habits that keep causing pain. Learn both so you can spot them early.

Helpful patterns

Anti-patterns

A balanced view: what the environment block does well, where it falls short, and the habits that keep you out of trouble.

Best practices in one place

1. Use clear capital names with underscores, and prefix related values, such as DOCKER_REGISTRY and DOCKER_IMAGE.
2. Keep the pipeline-level block short. Put stage-specific values inside their stages.
3. Never hard-code secrets. Always use the credentials helper or the binding step.
4. Use single quotes for commands that use secrets.
5. Trim and validate calculated values so empty or messy results fail loudly and early.
6. Compare text explicitly. When testing a flag stored as text, compare it to the exact word you expect.
7. Document unusual variables with a short comment beside them.
8. Review the block regularly and remove values that are no longer used.
9. Test changes with Replay before committing them.

The mistakes seen most often

Here is how the environment block tends to appear in real delivery pipelines. These are illustrative patterns, described in general terms, and not claims about the private setups of any particular company.

Jenkins is one of the most widely adopted automation servers, and large engineering organisations, including well-known technology companies, have publicly discussed running it at scale. What they share is not a secret trick but a discipline: settings live in one predictable place, secrets come from a protected store, and pipelines are reviewed like code. The patterns below show that discipline in practice.