Jenkins Pipeline Parameters: Complete Guide
Add parameters to Jenkins pipelines for flexible, interactive builds — strings, booleans, choices, and file parameters with real examples.
Table of Contents
- Parameter Types
- Using Parameters in Stages
- Conditional Logic with Parameters
- Real-World Examples
- Default Values and Validation
- Dynamic Parameters with Plugins
- Security Notes
- Triggering with Parameters
- Common Patterns
Parameter Types
| Type | Syntax | Use For |
|---|---|---|
string | string(name: 'VERSION', defaultValue: '1.0') | Version numbers, names |
text | text(name: 'NOTES', defaultValue: '') | Multi-line input |
booleanParam | booleanParam(name: 'DEPLOY', defaultValue: false) | Yes/no toggles |
choice | choice(name: 'ENV', choices: ['dev','staging','prod']) | Fixed options |
password | password(name: 'SECRET', defaultValue: '') | Hidden input (avoid) |
file | file(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
passwordparameter shows in build log if echoed. UsewithCredentialsinstead — parameters are visible to anyone with build-read access.- String parameters are injectable.
sh "./deploy.sh ${params.TARGET}"withTARGET=prod; rm -rf /runs the injection. Quote every parameter usage:sh "./deploy.sh '${params.TARGET}'"— or better, useenvvars andwithEnv. - 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()}"
}
}
}
}
Related Articles
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.