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.

Practice

1. What is the main purpose of the environment directive in a Jenkins pipeline?

easy

A. To define variables that can be used throughout the pipeline steps

B. To specify the build agent or node where the pipeline runs

C. To set the pipeline's timeout duration

D. To declare the stages of the pipeline

Solution

1. Step 1: Understand the role of environment directive

   The environment directive is used to set variables accessible in all pipeline steps.

2. Step 2: Compare with other pipeline directives

   Other directives like agent set the build node, and stages define pipeline stages, not environment variables.

3. Final Answer:

   To define variables that can be used throughout the pipeline steps -> Option A

4. Quick Check:

   Environment directive = set variables [OK]

Hint: Environment directive sets variables for all steps [OK]

Common Mistakes:

• Confusing environment with agent directive
• Thinking environment sets pipeline stages
• Assuming environment controls timeout

2. Which of the following is the correct syntax to set an environment variable GREETING with value Hello in a declarative Jenkins pipeline?

easy

A. environment { GREETING 'Hello' }

B. environment { GREETING: Hello }

C. environment { GREETING = Hello }

D. environment { GREETING = "Hello" }

Solution

1. Step 1: Recall environment variable syntax

   In Jenkins declarative pipelines, environment variables are set using environment { VAR = "value" } with quotes around string values.

2. Step 2: Check each option

   environment { GREETING = "Hello" } uses = with double quotes correctly.
   environment { GREETING: Hello } uses colon with unquoted Hello, syntax error (unresolved variable).
   environment { GREETING = Hello } misses quotes, syntax error.
   environment { GREETING 'Hello' } lacks assignment operator, syntax error.

3. Final Answer:

   environment { GREETING = "Hello" } -> Option D

4. Quick Check:

   Use double quotes for string values in environment [OK]

Hint: Use double quotes around string values in environment [OK]

Common Mistakes:

• Using colon instead of equals sign
• Omitting quotes around string values
• Using unquoted strings causing syntax errors

3. Given this Jenkins pipeline snippet:

pipeline {
  agent any
  environment {
    PATH = "/usr/local/bin"
    MESSAGE = "Build started"
  }
  stages {
    stage('Print') {
      steps {
        echo "$MESSAGE"
        sh 'echo $PATH'
      }
    }
  }
}

What will be the output when the Print stage runs?

medium

A. Build started
/usr/local/bin

B. $MESSAGE
$PATH

C. Build started
$PATH

D. Syntax error due to environment variables

Solution

1. Step 1: Understand environment variable usage

   The environment directive sets MESSAGE and PATH variables accessible in steps.

2. Step 2: Check echo and shell commands

   echo "$MESSAGE" prints the value of MESSAGE, which is "Build started". The shell command sh 'echo $PATH' prints the PATH variable value "/usr/local/bin".

3. Final Answer:

   Build started /usr/local/bin -> Option A

4. Quick Check:

   Environment variables expand correctly in echo and sh [OK]

Hint: Environment variables expand in echo and shell commands [OK]

Common Mistakes:

• Expecting literal variable names instead of values
• Confusing shell and Groovy variable syntax
• Assuming syntax error without cause

4. You wrote this environment block in your Jenkins pipeline:

environment {
  SECRET_KEY = secret123
}

But the pipeline fails with a syntax error. What is the most likely cause?

medium

A. Using an invalid variable name SECRET_KEY

B. Environment block must be inside a stage

C. Missing quotes around the string value

D. SECRET_KEY cannot contain numbers

Solution

1. Step 1: Check environment variable value syntax

   String values in environment variables must be quoted, e.g., SECRET_KEY = "secret123".

2. Step 2: Validate other options

   Variable names with underscores and numbers are valid. Environment block can be at pipeline level. Numbers in variable names are allowed.

3. Final Answer:

   Missing quotes around the string value -> Option C

4. Quick Check:

   Quote string values in environment variables [OK]

Hint: Always quote string values in environment directive [OK]

Common Mistakes:

• Forgetting quotes around strings
• Thinking variable names can't have underscores
• Placing environment block incorrectly

5. You want to set an environment variable VERSION dynamically based on a shell command output in a Jenkins declarative pipeline. Which approach correctly sets VERSION for use in later stages?

hard

A. Use environment { VERSION = sh(script: 'git describe --tags', returnStdout: true).trim() } directly in pipeline

B. Set VERSION inside a script block and use env.VERSION = ...

C. Declare VERSION as a parameter and assign shell output to it

D. Use environment { VERSION = "git describe --tags" } to run the command

Solution

1. Step 1: Understand environment directive limitations

   The environment directive cannot run shell commands directly; it only sets static values.

2. Step 2: Use script block to assign dynamic value

   Inside a script block, you can run shell commands and assign the output to env.VERSION for later use.

3. Step 3: Evaluate other options

   Use environment { VERSION = sh(script: 'git describe --tags', returnStdout: true).trim() } directly in pipeline tries to run shell in environment block which is invalid. Declare VERSION as a parameter and assign shell output to it misuses parameters. Use environment { VERSION = "git describe --tags" } to run the command assigns command string literally.

4. Final Answer:

   Set VERSION inside a script block and use env.VERSION = ... -> Option B

5. Quick Check:

   Dynamic env vars need script block assignment [OK]

Hint: Use script block to set dynamic environment variables [OK]

Common Mistakes:

• Trying to run shell commands directly in environment block
• Confusing parameters with environment variables
• Assigning command strings instead of output