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
• Triggering with Parameters

Parameter Types

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'
    }
}

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

• Jenkinsfile Generator Guide
• Jenkins GitHub Integration
• Jenkins Shared Libraries

---

Last Updated: October 2026
Author: CloudOpsGuide Team
Difficulty: Beginner
Estimated Reading Time: 11 minutes