Build Parameters
Parameters let you pass values into a build, such as a branch name, environment, or version number.
Syntax
parameters {
choice(name: 'ENV', choices: ['staging', 'production'])
}A parameterized job asks for input before it runs. This lets one job handle many situations — for example, deploy to staging or production based on a choice.
Parameter types
- String — free text, like a version number.
- Choice — a dropdown of allowed values.
- Boolean — a checkbox (true/false).
- Password — a masked secret input.
Using the value
Parameters become environment variables inside the build. In a shell step you read them as $NAME; in a declarative pipeline as params.NAME.
Example
pipeline {
agent any
parameters {
choice(name: 'ENVIRONMENT', choices: ['staging', 'production'], description: 'Where to deploy')
string(name: 'VERSION', defaultValue: '1.0.0', description: 'Release version')
booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run the test suite?')
}
stages {
stage('Deploy') {
steps {
echo "Deploying version ${params.VERSION} to ${params.ENVIRONMENT}"
}
}
}
}When to use it
- A deploy job accepts a choice parameter for target environment so the same job deploys to staging or production.
- A release pipeline takes a string parameter for the version number to tag the Docker image correctly.
- A boolean parameter lets testers skip slow integration tests when they only need a quick smoke-test run.
More examples
Declare parameters in Jenkinsfile
Declares three parameter types — choice, string, and boolean — that appear in the Build with Parameters form.
pipeline {
agent any
parameters {
choice(name: 'ENV', choices: ['staging', 'production'], description: 'Deploy target')
string(name: 'VERSION', defaultValue: 'latest', description: 'Image tag')
booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run test suite')
}
stages {
stage('Info') {
steps { echo "Deploying ${params.VERSION} to ${params.ENV}" }
}
}
}Use a parameter in a shell step
Reads the VERSION and ENV parameters to run a conditional Helm deployment only to production.
stage('Deploy') {
when { expression { params.ENV == 'production' } }
steps {
sh """
helm upgrade myapp ./chart \\
--set image.tag=${params.VERSION} \\
--namespace production
"""
}
}Pass parameter when triggering downstream job
Forwards the current job's parameters to a downstream integration-test job after a successful build.
post {
success {
build job: 'run-integration-tests',
parameters: [
string(name: 'APP_VERSION', value: params.VERSION),
string(name: 'TARGET_ENV', value: params.ENV)
]
}
}
Discussion