How to Use Choice Parameter in Jenkins for Job Configuration

In Jenkins, use the Choice Parameter to let users pick from predefined options before starting a build. Add it in the job configuration under Parameters, then define the choices as a list. The selected choice is available as an environment variable during the build.

Syntax

The Choice Parameter in Jenkins is defined in the job configuration with these parts:

• Name: The variable name used in the build.
• Description: Explains what the parameter is for.
• Choices: A list of options separated by new lines.

This parameter appears as a dropdown menu when you start the job.

groovy

properties([
  parameters([
    choice(name: 'ENVIRONMENT', choices: ['dev', 'test', 'prod'], description: 'Select the deployment environment')
  ])
])

Example

This example shows a Jenkins pipeline with a choice parameter named ENVIRONMENT. The user can select 'dev', 'test', or 'prod'. The pipeline prints the selected environment.

groovy

pipeline {
  agent any
  parameters {
    choice(name: 'ENVIRONMENT', choices: ['dev', 'test', 'prod'], description: 'Select the deployment environment')
  }
  stages {
    stage('Show Choice') {
      steps {
        echo "Selected environment is: ${params.ENVIRONMENT}"
      }
    }
  }
}

Output

[Pipeline] echo
Selected environment is: test

Common Pitfalls

Common mistakes when using choice parameters include:

• Not separating choices with new lines, causing Jenkins to treat them as one option.
• Using spaces or special characters in choice names that may cause issues in scripts.
• Forgetting to reference the parameter correctly in the pipeline script (use params.PARAM_NAME).

Always test your parameter to ensure it behaves as expected.

groovy

/* Wrong way: choices as a single string with commas */
parameters {
  choice(name: 'COLOR', choices: 'red,green,blue', description: 'Pick a color')
}

/* Right way: choices as a list or newline-separated string */
parameters {
  choice(name: 'COLOR', choices: ['red', 'green', 'blue'], description: 'Pick a color')
}

Quick Reference

Field	Description	Example
Name	Variable name to use in scripts	ENVIRONMENT
Description	Explains the parameter purpose	Select the deployment environment
Choices	List of options separated by new lines or array	dev\ntest\nprod
Usage in Pipeline	Access selected value	params.ENVIRONMENT

Key Takeaways

Add a choice parameter in Jenkins job configuration to let users select from predefined options.

Define choices as a list or newline-separated string for proper dropdown display.

Access the selected choice in pipeline scripts using params.PARAM_NAME syntax.

Avoid commas inside the choices string; use separate lines or arrays instead.

Test your choice parameter to ensure it works as expected before using in production.