Jenkins Environment Variables and Parameters

Environment variables and parameters let you write flexible pipelines that adapt to different situations without changing the code. Variables carry information through the build. Parameters let users pass values into a build before it starts.

Think of a variable as a labeled box. You put a value in the box once and refer to the label everywhere you need that value. When you need to change the value, you update just the box — not every place you used it.

Jenkins Built-In Environment Variables

Jenkins automatically provides a set of variables in every build. You can use these in your pipeline without defining them.

Most Useful Built-In Variables

View all available variables for your Jenkins instance at:

http://your-jenkins:8080/pipeline-syntax/globals

Using Built-In Variables in a Pipeline

pipeline {
    agent any
    stages {
        stage('Info') {
            steps {
                echo "Build #${env.BUILD_NUMBER} of ${env.JOB_NAME}"
                echo "Commit: ${env.GIT_COMMIT}"
                echo "Branch: ${env.GIT_BRANCH}"
                echo "Build URL: ${env.BUILD_URL}"

                sh "docker build -t myapp:${env.BUILD_NUMBER} ."
                sh "echo Build completed on agent: ${env.NODE_NAME}"
            }
        }
    }
}

Custom Environment Variables

Define your own variables in the environment block at the pipeline level or inside a specific stage. Stage-level variables override pipeline-level variables with the same name.

pipeline {
    agent any

    environment {
        // Pipeline-level variables (available everywhere)
        APP_NAME    = 'inventory-service'
        DOCKER_REG  = 'registry.mycompany.com'
        IMAGE_TAG   = "${env.BUILD_NUMBER}"
        IMAGE_FULL  = "${DOCKER_REG}/${APP_NAME}:${IMAGE_TAG}"
    }

    stages {
        stage('Build') {
            environment {
                // Stage-level variable (only in this stage)
                MAVEN_OPTS = '-Xmx512m'
            }
            steps {
                sh "mvn clean package"
                sh "docker build -t ${IMAGE_FULL} ."
            }
        }

        stage('Push') {
            steps {
                sh "docker push ${IMAGE_FULL}"
            }
        }
    }
}

Parameters: Inputs Before the Build Starts

Parameters let users (or other systems) pass values into a build when they trigger it. Instead of hardcoding a deployment environment, a user can choose "staging" or "production" each time they run the job.

How Parameters Look in Jenkins UI

When a parameterized job is triggered manually:

  Jenkins shows a form:
  ┌─────────────────────────────────────────┐
  │  Build with Parameters                  │
  │                                         │
  │  ENVIRONMENT: [ staging ▼ ]             │
  │               (staging / production)    │
  │                                         │
  │  APP_VERSION: [_________________]       │
  │  (default: 1.0.0)                       │
  │                                         │
  │  RUN_TESTS:   [✓] (checked by default)  │
  │                                         │
  │  DEPLOY_MESSAGE: [_____________________]│
  │                                         │
  │              [ Build ]                  │
  └─────────────────────────────────────────┘

Defining Parameters in Declarative Pipeline

pipeline {
    agent any

    parameters {
        // Dropdown selection
        choice(
            name: 'ENVIRONMENT',
            choices: ['staging', 'production', 'dev'],
            description: 'Where to deploy this build'
        )

        // Free text input
        string(
            name: 'APP_VERSION',
            defaultValue: '1.0.0',
            description: 'Version number to tag this build'
        )

        // Checkbox (true/false)
        booleanParam(
            name: 'RUN_TESTS',
            defaultValue: true,
            description: 'Check to run unit tests'
        )

        // Multi-line text
        text(
            name: 'DEPLOY_MESSAGE',
            defaultValue: '',
            description: 'Optional message to include in deployment log'
        )

        // Password (masked in logs)
        password(
            name: 'DB_PASSWORD',
            defaultValue: '',
            description: 'Database password for this deployment'
        )
    }

    stages {
        stage('Show Parameters') {
            steps {
                echo "Deploying to: ${params.ENVIRONMENT}"
                echo "Version: ${params.APP_VERSION}"
                echo "Run tests: ${params.RUN_TESTS}"
            }
        }

        stage('Test') {
            when {
                expression { return params.RUN_TESTS }
            }
            steps {
                sh 'mvn test'
            }
        }

        stage('Deploy') {
            steps {
                sh "deploy.sh --env ${params.ENVIRONMENT} --version ${params.APP_VERSION}"
            }
        }
    }
}

Accessing Parameters vs Environment Variables

Parameters:    Use params.PARAM_NAME
               Example: params.ENVIRONMENT

Environment:   Use env.VAR_NAME or just ${VAR_NAME} in shell
               Example: env.BUILD_NUMBER

In shell steps, both are available as system environment variables:
  sh "echo Deploying ${params.ENVIRONMENT} build ${env.BUILD_NUMBER}"

Setting Variables Dynamically During a Build

Sometimes you need to create a variable during the build and use it in later stages. Use the script block to set a variable on the environment object.

pipeline {
    agent any

    stages {
        stage('Determine Version') {
            steps {
                script {
                    // Read version from a file generated by Maven
                    def version = sh(
                        script: "mvn help:evaluate -Dexpression=project.version -q -DforceStdout",
                        returnStdout: true
                    ).trim()

                    env.APP_VERSION = version
                    echo "Detected version: ${env.APP_VERSION}"
                }
            }
        }

        stage('Build Docker Image') {
            steps {
                // APP_VERSION is now available here
                sh "docker build -t myapp:${env.APP_VERSION} ."
            }
        }
    }
}

Environment Variables from Credentials

Inject a credential into an environment variable securely using the credentials() helper. Jenkins masks the value in console output, so it never appears in logs.

environment {
    // Loads a "Username with password" credential
    // Creates: DOCKER_CREDS_USR and DOCKER_CREDS_PSW automatically
    DOCKER_CREDS = credentials('docker-registry-creds')
}

steps {
    sh "docker login ${DOCKER_REG} -u ${DOCKER_CREDS_USR} -p ${DOCKER_CREDS_PSW}"
}

Key Points

• Jenkins provides built-in variables like BUILD_NUMBER, JOB_NAME, and GIT_COMMIT in every build.
• Define custom variables in the environment block — at pipeline level for all stages, or at stage level for one stage.
• Parameters let users choose values at build time (dropdown, text input, checkbox).
• Access parameters with params.NAME and environment variables with env.NAME.
• Use the credentials() helper to load secrets as environment variables — Jenkins masks them in logs.