A Jenkinsfile is a text file that contains the definition of a Jenkins Pipeline and is checked into source control. It is used to automate parts of the CI/CD pipeline, defining tasks and parameters that Jenkins can use to run those tasks.
One way to parameterize a Jenkinsfile is to use parameters. Parameters allow you to pass data into a Jenkinsfile at runtime. This can be useful for environment-specific configurations or passing in values specific to the current build.
In this tutorial, you will learn how to use Jenkinsfile parameters in a Jenkins Pipeline.
Requirements:
- Basic knowledge of Jenkins and the Jenkins Pipeline plugin
- A Jenkins instance with the Jenkins Pipeline plugin installed
- A Jenkinsfile in your source control repository
Jenkins Declare Parameters
Before using any parameters in a Jenkinsfile, we first need to declare them in the Jenkinsfile. We can accomplish this by using the parameters block.
Take for example the pipeline section shown below:
parameters {
string(name: 'ENVIRONMENT', defaultValue: 'dev', description: 'The environment to deploy to')
boolean(name: 'DEPLOY', defaultValue: false, description: 'Whether to deploy or not')
}
...
}
In the example above, the Jenkinsfile contains two parameters as:
- ENVIRONMENT – a string parameter with a default value of ‘dev.’
- DEPLOY – a Boolean parameter with a default value of false.
We can specify any number of parameters within the parameters block. Jenkins supports various parameter types including:
- string parameter types – used to store a sequence of characters
- Text parameters – similar to string parameter type but can span multiple lines. An example is a description parameter, as shown in the previous example.
- BooleanParam – BooleanParam or Boolean is used to store truthy or falsy values.
- Choice – choice parameters, on the other hand, allow you to store multiple choice values.
- Password – password parameters are used to store passwords and authentication credentials.
Jenkins Access Parameters
Once we have declared your parameters in the Jenkinsfile, we can access their values using the $params object.
For example, to access the value of the ENVIRONMENT parameter in a stage, we can use $params.ENVIRONMENT.
Example Demonstration
Take the example pipeline below that demonstrates how to use various parameter types in Jenkins:
agent any
parameters {
string(name: 'name', defaultValue: 'Jenkins', description: 'username')
text(name: 'desc', defaultValue: '', description: 'description about the user. ')
booleanParam(name: 'toggle', defaultValue: true, description: 'Enable/Disable')
choice(name: 'choice', choices: [1,2,3,4,5], description: 'choose a value')
password(name: 'passwd', defaultValue: 'secret', description: 'provide password')
}
stages {
stage('Example') {
steps {
echo "Hello ${params.name}"
echo "desc: ${params.desc}"
echo "toggle: ${params.toggle}"
echo "choice: ${params.choice}"
echo "password: ${params.passwd}"
}
}
}
}
Output:
Jenkins Set Value
In a declarative Jenkinsfile, we can set a value of a given parameter as shown in the example below:
parameters {
string(name: 'ENVIRONMENT', defaultValue: 'dev', description: 'The environment to deploy to', value: 'prod')
…
}
In this example, the ENVIRONMENT parameter will always be set to ‘prod’ when running the build.
When working in a scripted Jenkinsfile, we can set the value for a given parameter using the build command. An example demonstaration is as shown:
…
stage('Deploy') {
build job: 'deploy', parameters: [[$class: 'StringParameterValue', name: 'ENVIRONMENT', value: 'prod']]
}
}
In this case, the pipeline value of the ENVIRONMENT variable is always set to prod.
Setting Parameter Default Value
It is a good idea to set default values for the defined parameters if the value is not provided during the build process. We can accomplish this by using the defaultValue parameter as shown in the example below:
string(name: 'ENVIRONMENT', defaultValue: 'dev', description: 'The environment to deploy to')
}
In this case, the ENVIRONMENT parameter will default to ‘dev’ if a value is not provided during the build.
Conclusion
In this article, you discovered how to use Jenkinsfile parameters in a Jenkins Pipeline. You learned how to declare parameters in the Jenkinsfile, access their values in stages, and set the parameter value during the build process. Finally, we discovered how to use the defaultValue parameter to assign a default value to a given parameter if the value is missing.
Using Jenkinsfile parameters, we can make our Jenkins Pipeline more flexible and easier to customize for different environments and use cases.
