Environment directive in Jenkins - Commands & Configuration

Introduction

Sometimes your Jenkins pipeline needs to use specific settings or secrets like API keys or server addresses. The environment directive lets you set these values so your pipeline steps can use them easily.

When you want to set a database URL that your build needs to connect to.

When you need to provide an API token for a deployment step.

When you want to define a common version number used across multiple steps.

When you want to keep sensitive information like passwords out of your script code.

When you want to reuse environment variables in different parts of your pipeline.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  environment {
    APP_VERSION = '1.2.3'
    DEPLOY_ENV = 'staging'
    API_TOKEN = credentials('my-api-token')
  }
  stages {
    stage('Build') {
      steps {
        echo "Building version ${APP_VERSION} for ${DEPLOY_ENV}"
      }
    }
    stage('Deploy') {
      steps {
        echo "Deploying with token ${API_TOKEN}"
      }
    }
  }
}

The environment block defines variables available to all stages and steps in the pipeline.

APP_VERSION and DEPLOY_ENV are simple string variables.

API_TOKEN uses Jenkins credentials plugin to securely inject a secret.

These variables can be accessed in steps using ${VARIABLE_NAME}.

Commands

This command updates the Jenkins job with the new Jenkinsfile containing the environment directive so Jenkins knows about the environment variables.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully

This command starts a build of the Jenkins pipeline named 'my-pipeline' and shows the build output in the console.

Terminal

jenkins-cli build my-pipeline -s

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Building version 1.2.3 for staging

[Pipeline] echo

Deploying with token ********

[Pipeline] End of Pipeline

Finished: SUCCESS

→

-s - Show console output after build completes

This command fetches the console output of the last build of the 'my-pipeline' job to verify environment variables were used correctly.

Terminal

jenkins-cli console my-pipeline

Expected Output

Building version 1.2.3 for staging

Deploying with token ********

Key Concept

If you remember nothing else from this pattern, remember: the environment directive sets variables once so all pipeline steps can use them safely and consistently.

Common Mistakes

Defining environment variables inside a stage instead of the environment block.

Variables defined inside a stage are not available globally and may cause errors in other stages.

Always define shared environment variables inside the top-level environment block.

Hardcoding sensitive data directly in the Jenkinsfile.

This exposes secrets in the source code and Jenkins logs, risking security breaches.

Use Jenkins credentials plugin and reference secrets with the credentials() function.

Using incorrect syntax like missing quotes around string values.

Jenkinsfile parsing fails and the pipeline will not run.

Always quote string values in the environment block, e.g., APP_VERSION = '1.2.3'.

Summary

Use the environment directive in Jenkinsfile to set variables accessible to all pipeline steps.

Define simple strings or secure credentials inside the environment block for reuse.

Run and verify the pipeline to ensure environment variables are correctly injected and used.