How to Inject Environment Variables in Jenkins

Need a build to use a value without hard-coding it in a script? You can inject environment variables in Jenkins with Pipeline settings, credential bindings, or a Freestyle job setup. Start with the simplest method that fits the job, then narrow secret access to the command that needs it.

Step 1: Choose the Right Jenkins Method for Your Job

Pick the method based on where the value comes from and how long it needs to exist. For a non-sensitive setting in a Pipeline, use the built-in environment directive. For a stored password or token, use Jenkins Credentials with the Credentials Binding plugin. For a Freestyle job that needs injected properties, EnvInject is one option.

EnvInject can set variables at the node or job level, or after source control checkout. It also records build variables for later review.

Jenkins also warns that environment values can affect the programs running in a build. A changed PATH, for example, can change which executable a script finds. Review who can set variables, and treat values from user-controlled inputs as untrusted.

For secrets, decide whether Jenkins should store and bind the credential or whether a central manager should provide it at runtime. EnvManager runs a command with selected values, such as STRIPE_KEY, rather than writing the secret into a script. Its --only option makes the allowed set explicit. If you’re weighing command-level injection, this guide to CLI tools that inject secrets without logging them explains what to check in a wrapper.

Choose by scope: static, non-secret value means environment; a stored Jenkins credential means credential binding; a Freestyle property setup may call for EnvInject.

Step 2: Set Variables in a Declarative Jenkins Pipeline

Use a top-level environment block when every stage needs the same value. Place the block inside one stage when only that stage should receive it. This scope difference is easy to miss: a stage-level value won’t carry into the next stage.

pipeline {
  agent any
  environment {
    APP_MODE = 'test'
  }
  stages {
    stage('Test') {
      steps {
        sh 'echo "$APP_MODE"'
      }
    }
    stage('Build') {
      steps {
        echo "Mode: ${env.APP_MODE}"
      }
    }
  }
}

In a shell step, use the shell’s variable form, such as $APP_MODE. In Groovy Pipeline code, read it through env.APP_MODE. Use double quotes when you want Groovy to substitute an expression such as ${env.APP_MODE}. Single-quoted Groovy strings don’t perform that interpolation.

Keep ordinary settings in the Jenkinsfile only when they’re safe to store in source control. Don’t put real passwords or API tokens in the file. Use the built-in environment directive to define values for a whole Pipeline or a single stage.

Jenkins and plugins can also provide values at runtime. A Pipeline that checks out a Git repository can use values such as GIT_COMMIT and GIT_BRANCH when the Git plugin sets them. For example, add a short commit ID to a report filename from a shell step:

sh 'echo "report-${GIT_COMMIT:0:7}.txt"'

The shell syntax above takes the first seven characters in a Bash environment. If you need the value in Groovy, use env.GIT_COMMIT instead. Confirm the variable exists in your job before depending on it, especially if the job’s checkout flow differs.

By now, each value should have a clear scope and a matching way to read it. Keep stage-only values inside the stage that uses them.

Step 3: Inject Dynamic Values with withEnv in Jenkins

Use withEnv when a value should apply only to a block of Pipeline steps. It sets environment entries for the enclosed steps, then the block ends. This is useful for temporary settings such as a test mode or a value calculated during the run.

pipeline {
  agent any
  stages {
    stage('Test') {
      steps {
        script {
          def buildLabel = "run-${env.BUILD_NUMBER}"
          withEnv(["BUILD_LABEL=${buildLabel}"]) {
            sh 'echo "$BUILD_LABEL"'
          }
        }
      }
    }
  }
}

For values generated by a command, capture standard output and trim the line break before assigning it. The sh step can return standard output when you set returnStdout: true.

script {
  def shortCommit = sh(
    script: 'git rev-parse --short HEAD',
    returnStdout: true
  ).trim()
  withEnv(["SHORT_COMMIT=${shortCommit}"]) {
    sh 'echo "$SHORT_COMMIT"'
  }
}

Use a shared-library helper when several Jenkinsfiles need the same calculation. Keep the helper focused: return the value, then let the Pipeline decide where to set it. That makes the scope easier to see during a review.

For stored secrets, use a credential binding rather than putting the secret in a plain withEnv string. A typical Pipeline binding looks like this:

withCredentials([string(credentialsId: 'deploy-token', variable: 'DEPLOY_TOKEN')]) {
  sh 'deploy-tool --token "$DEPLOY_TOKEN"'
}

Use a specific credential ID, such as deploy-token, instead of a vague label like password. Binding helps Jenkins mask supported secret values in console output, but masking is not a sandbox. A process running in the build can still read environment values it receives.

If you want a command to receive only selected secrets, EnvManager’s CLI can run that command with an explicit allow-list. The EnvManager run command documentation shows the options and explains how the command’s output is scrubbed. For example:

envmanager run --only STRIPE_KEY -- npm run seed

Keep the CLI authentication available only to the job that needs it. The --only flag narrows what the child command gets, but it doesn’t turn that command into an isolated sandbox.

Step 4: Configure Environment Variables for Jenkins Freestyle Jobs

In a Freestyle job, set basic build variables in the job configuration or use a plugin when you need injected properties. If you use EnvInject, install and configure it through Jenkins’ plugin and job settings. The labels can vary by version, but the job configuration includes options for adding properties or loading them from a file.

For a small, non-secret value, enter a name and value in the job’s build environment settings. To load a properties file, point the job to a file in the workspace at the point when that file is available. If the values depend on a checkout, configure injection after source control checkout. Otherwise Jenkins may try to read the file before the checkout creates it.

Then use the variable in a build step. A shell step can read it as $OUTPUT_DIR; a Windows batch step uses %OUTPUT_DIR%. Quote shell variables where the value may contain spaces. On Windows, take care with values that contain command metacharacters, since a batch script can interpret them as code.

EnvInject also supports injection at node or controller level, which can affect more than one job. Use that wider scope only when the value truly belongs across those builds. A job-level setting is easier to reason about when just one job needs the value.

To inspect a build, open its page and look for the injected variables action. The plugin can also expose variables through a path shaped like /job/JOB_NAME/BUILD_NUMBER/injectedEnvVars/export. It supports XML, JSON, and text output. Treat that view as sensitive if a job’s variables include secrets.

For a classic job, EnvInject can help with properties and build-time inspection. Don’t choose it as a shortcut for Pipeline behavior, since its Pipeline compatibility has known limits.

Step 5: Handle Credentials, Verify Values, and Troubleshoot

Store secrets as Jenkins credentials, then bind them only around the steps that need them. Credentials Binding supports secret text, files, and username/password bindings, including separate variables for a username and password. A shell example might look like this:

withCredentials([usernamePassword(
  credentialsId: 'artifact-repo',
  usernameVariable: 'REPO_USER',
  passwordVariable: 'REPO_PASSWORD'
)]) {
  sh 'upload-tool --user "$REPO_USER" --password "$REPO_PASSWORD"'
}

Use a real credential ID created in Jenkins, and don’t echo the secret as a debugging shortcut. Jenkins masking replaces supported credential values in console output, but careless scripts can still expose data through transformations or other output. Secrets need care even when Jenkins stores them as credentials.

For centralized secrets, a vault plugin may fit a team’s setup. Some vault plugins provide a wrapper block, so values are available inside that block rather than everywhere in the job. If a step outside the block needs a value, move that step inside or bind the value again. Don’t assume the variable remains available after the block ends.

When a value is missing, check these points in order:

• Scope: Is it global, job-level, or stage-only? A stage variable won’t appear in a later stage.
• Timing: Does the properties file exist when injection runs? Set checkout-dependent values after checkout.
• Name: Does the shell use $NAME, while Windows batch uses %NAME%?
• Interpolation: Does Groovy need a double-quoted string to evaluate ${env.NAME}?
• Credential binding: Is the credential ID correct, and is the step inside the binding block?

To inspect ordinary runtime variables on a Linux agent, run printenv or env in a controlled build. Avoid dumping a full environment when secrets might be present. Print a variable’s name or a safe, non-secret value instead. For Windows agents, use the appropriate command for that shell.

For a long-running Pipeline, set a timeout so a stuck build doesn’t wait forever. Declarative Pipeline supports a timeout option, and timestamps can be enabled to make it easier to see when each log line ran. These controls help diagnose delays; they don’t fix a missing variable or an incorrect scope.

EnvManager is another option when a job needs runtime injection and output scrubbing. Use envmanager run --only KEY_NAME -- command to limit the variables the command can use. Keep its CLI authentication out of source files, and grant it only to the job that requires those secrets.

FAQ: Injecting Environment Variables in Jenkins

How do I set an environment variable in a Jenkins Pipeline?

Use the environment directive in a Declarative Pipeline. Put it at the Pipeline level for a value shared across stages, or inside one stage for a value used only there. Read it in a shell with $NAME, or in Groovy with env.NAME. Don’t store a real secret directly in the Jenkinsfile.

How do I use Jenkins credentials as environment variables?

Use the Credentials Binding plugin to bind a stored credential around the steps that need it. For a secret text value, use a string binding; for a login pair, use a username/password binding. Give the credential a clear ID, avoid printing its value, and keep the command inside the binding block.

Why is my Jenkins stage variable empty in the next stage?

A variable set in a stage-level environment block is limited to that stage. Move it to the top-level Pipeline environment if later stages need the same static value. If the value is generated at runtime, assign it with a Pipeline step and make sure the later step receives it in the right scope.

Can EnvInject be used with Jenkins Pipeline?

For Declarative Pipeline jobs, prefer the built-in environment directive and credential binding. EnvInject is more suited to Freestyle jobs that need injected properties or build-variable capture.

Conclusion

Use Jenkins’ native Pipeline directives for ordinary values, and credential binding for secrets stored in Jenkins. If you need runtime-only injection, test a narrowly scoped command with EnvManager’s --only option. Next, run a build with a harmless test value and confirm its scope before adding production credentials.