Jenkins

Jenkins Pipeline Parameters: Complete Guide

Beginner
11 minutes
Updated October 2026

Add parameters to Jenkins pipelines for flexible, interactive builds — strings, booleans, choices, and file parameters with real examples.

Table of Contents

Parameter Types

TypeSyntaxUse For
stringstring(name: 'VERSION', defaultValue: '1.0')Version numbers, names
texttext(name: 'NOTES', defaultValue: '')Multi-line input
booleanParambooleanParam(name: 'DEPLOY', defaultValue: false)Yes/no toggles
choicechoice(name: 'ENV', choices: ['dev','staging','prod'])Fixed options
passwordpassword(name: 'SECRET', defaultValue: '')Hidden input (avoid)
filefile(name: 'UPLOAD', description: 'Upload config')File uploads

Using Parameters in Stages

pipeline {
    agent any

    parameters {
        string(name: 'VERSION', defaultValue: '1.0.0', description: 'Release version')
        choice(name: 'ENVIRONMENT', choices: ['dev', 'staging', 'prod'], description: 'Target environment')
        booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run test suite?')
        text(name: 'RELEASE_NOTES', defaultValue: '', description: 'Release notes')
    }

    stages {
        stage('Build') {
            steps {
                echo "Building version ${params.VERSION} for ${params.ENVIRONMENT}"
                sh "./build.sh --version ${params.VERSION}"
            }
        }

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

        stage('Deploy') {
            when {
                allOf {
                    expression { params.ENVIRONMENT != 'dev' }
                    expression { params.RUN_TESTS }
                }
            }
            steps {
                echo "Deploying to ${params.ENVIRONMENT}"
                sh "./deploy.sh ${params.ENVIRONMENT} ${params.VERSION}"
            }
        }
    }
}

Access via params.PARAM_NAME — always.

Conditional Logic with Parameters

Simple Boolean Check

stage('Deploy') {
    when {
        expression { params.DEPLOY }
    }
    steps { sh './deploy.sh' }
}

Environment-Specific Stages

stage('Deploy Staging') {
    when { expression { params.ENVIRONMENT == 'staging' } }
    steps { sh './deploy.sh staging' }
}

stage('Deploy Production') {
    when { expression { params.ENVIRONMENT == 'prod' } }
    input { message 'Deploy to production?' }
    steps { sh './deploy.sh prod' }
}

Multiple Conditions

when {
    allOf {                                    // AND
        expression { params.ENVIRONMENT == 'prod' }
        expression { params.DEPLOY }
        branch 'main'
    }
}
when {
    anyOf {                                    // OR
        expression { params.ENVIRONMENT == 'staging' }
        expression { params.ENVIRONMENT == 'prod' }
    }
}

Real-World Examples

Version Bump and Deploy

parameters {
    choice(name: 'BUMP', choices: ['patch', 'minor', 'major'], description: 'Version bump')
    booleanParam(name: 'DEPLOY', defaultValue: false, description: 'Deploy after build?')
    string(name: 'DOCKER_TAG', defaultValue: '', description: 'Custom tag (leave empty for auto)')
}

stages {
    stage('Version Bump') {
        steps {
            script {
                def version = sh(
                    script: "npm version ${params.BUMP} --no-git-tag-version",
                    returnStdout: true
                ).trim()
                env.NEW_VERSION = version
                echo "Bumped to: ${version}"
            }
        }
    }

    stage('Docker Build') {
        steps {
            script {
                def tag = params.DOCKER_TAG ?: env.NEW_VERSION
                sh "docker build -t myapp:${tag} ."
                env.IMAGE_TAG = tag
            }
        }
    }

    stage('Deploy') {
        when { expression { params.DEPLOY } }
        steps {
            sh "kubectl set image deployment/myapp myapp=myapp:${env.IMAGE_TAG}"
        }
    }
}

Multi-Environment Terraform

parameters {
    choice(name: 'ENVIRONMENT', choices: ['dev', 'staging', 'prod'])
    choice(name: 'ACTION', choices: ['plan', 'apply', 'destroy'])
    booleanParam(name: 'AUTO_APPROVE', defaultValue: false)
}

stages {
    stage('Terraform') {
        steps {
            sh """
                terraform init -backend-config="env=${params.ENVIRONMENT}"
                terraform ${params.ACTION} \
                  -var="environment=${params.ENVIRONMENT}" \
                  ${params.AUTO_APPROVE ? '-auto-approve' : ''}
            """
        }
    }
}

Default Values and Validation

Required Parameters

Jenkins doesn't enforce required params, but you can validate:

stage('Validate') {
    steps {
        script {
            if (!params.VERSION?.trim()) {
                error("VERSION parameter is required")
            }
            if (!params.VERSION ==~ /^\d+\.\d+\.\d+$/) {
                error("VERSION must be in X.Y.Z format")
            }
        }
    }
}

Dynamic Defaults with Environment

parameters {
    string(name: 'IMAGE_TAG', defaultValue: env.BRANCH_NAME == 'main' ? 'latest' : env.BRANCH_NAME)
}

Input Step for Runtime Prompts

stage('Deploy Approval') {
    when { expression { params.ENVIRONMENT == 'prod' } }
    steps {
        script {
            def approval = input(
                message: 'Deploy to production?',
                parameters: [
                    choice(name: 'CONFIRM', choices: ['no', 'yes'], description: 'Are you sure?'),
                    text(name: 'REASON', description: 'Reason for deployment')
                ]
            )
            if (approval.CONFIRM != 'yes') {
                error('Deployment cancelled')
            }
            echo "Deploying because: ${approval.REASON}"
        }
        sh './deploy.sh prod'
    }
}

Dynamic Parameters with Plugins

The built-in choice parameter is static — the dropdown lists whatever you hardcoded. For dynamic choices ("pick from the environments that actually exist"), the Active Choices plugin runs a Groovy script at parameter-render time:

// Active Choices parameter (configured in job, not Jenkinsfile)
// Lists all git branches dynamically:
import jenkins.model.Jenkins
def job = Jenkins.instance.getItemByFullName("my-job")
def branches = sh(script: 'git ls-remote --heads origin', returnStdout: true)
return branches.split('\n').collect { it.split('/').last() }

Other useful plugins:

  • Extended Choice Parameter — multi-select checkboxes, file-driven choices
  • Cascade Choice — dependent dropdowns (pick environment → its services appear)
  • List Git Branches Parameter — direct git branch picker without scripting

Dynamic parameters are the difference between "the dropdown has the right options" and "the dropdown lists what someone remembered to add six months ago."

Security Notes

  • password parameter shows in build log if echoed. Use withCredentials instead — parameters are visible to anyone with build-read access.
  • String parameters are injectable. sh "./deploy.sh ${params.TARGET}" with TARGET=prod; rm -rf / runs the injection. Quote every parameter usage: sh "./deploy.sh '${params.TARGET}'" — or better, use env vars and withEnv.
  • Parameters persist in build history. Every build stores its parameters in the job's build.xml — secrets passed as parameters live in plaintext on the Jenkins controller's disk.
  • Restrict who can rebuild with parameters. A parameter that changes the deploy target is a parameter that changes what gets deployed — RBAC on parameter use matters.

Triggering with Parameters

From Webhooks/API

# Trigger with parameters
curl -X POST "https://jenkins.example.com/job/myjob/buildWithParameters" \
  --user user:token \
  --data "VERSION=2.0.0&ENVIRONMENT=prod&DEPLOY=true"

From Another Pipeline

// In an upstream pipeline
build(
    job: 'deploy-pipeline',
    parameters: [
        string(name: 'VERSION', value: env.NEW_VERSION),
        string(name: 'ENVIRONMENT', value: 'staging'),
        booleanParam(name: 'DEPLOY', value: true)
    ],
    wait: true
)

Common Patterns

Parameter-Driven Feature Flags

parameters {
    booleanParam(name: 'SKIP_TESTS', defaultValue: false)
    booleanParam(name: 'CLEAN_BUILD', defaultValue: false)
    booleanParam(name: 'SKIP_SCAN', defaultValue: false)
}

stage('Build') {
    steps {
        sh """
            ./build.sh \
              ${params.CLEAN_BUILD ? '--clean' : ''} \
              ${params.SKIP_TESTS ? '--skip-tests' : ''}
        """
    }
}

Multi-Select (workaround)

parameters {
    string(name: 'SERVICES', defaultValue: 'api,web', description: 'Comma-separated service names')
}

stage('Deploy Services') {
    steps {
        script {
            params.SERVICES.split(',').each { service ->
                echo "Deploying: ${service.trim()}"
                sh "./deploy.sh ${service.trim()}"
            }
        }
    }
}
Written & Reviewed by Yasir Masood, CloudOpsGuide Editor

Our tutorials and troubleshooting runbooks are written by a DevOps practitioner with hands-on experience operating Kubernetes, Terraform, CI/CD pipelines, and Linux infrastructure in production. Commands, manifests, and configurations are verified against current tooling releases. Learn more about our editorial process or report a correction or outdated flag.