How to Use String Parameter in Jenkins Pipeline

In Jenkins, you can use a string parameter to accept text input when starting a job. Define it in the pipeline with parameters { string(name: 'PARAM_NAME', defaultValue: 'default', description: 'desc') } and access it using params.PARAM_NAME inside your pipeline script.

Syntax

The string parameter in Jenkins pipeline is defined inside the parameters block. It requires a name to identify the parameter, an optional defaultValue to pre-fill the input box, and an optional description to explain the parameter's purpose.

Inside the pipeline script, you access the parameter value using params.PARAM_NAME.

groovy

pipeline {
  agent any
  parameters {
    string(name: 'GREETING', defaultValue: 'Hello', description: 'Enter a greeting message')
  }
  stages {
    stage('Example') {
      steps {
        echo "Message: ${params.GREETING}"
      }
    }
  }
}

Example

This example shows a Jenkins pipeline that asks for a string input named GREETING. When you run the job, Jenkins will prompt you to enter a greeting message. The pipeline then prints the message using echo.

groovy

pipeline {
  agent any
  parameters {
    string(name: 'GREETING', defaultValue: 'Hello, Jenkins!', description: 'Enter a greeting message')
  }
  stages {
    stage('Print Greeting') {
      steps {
        echo "Greeting message is: ${params.GREETING}"
      }
    }
  }
}

Output

[Pipeline] echo
Greeting message is: Hello, Jenkins!

Common Pitfalls

• Forgetting to define the parameters block causes params.PARAM_NAME to be empty.
• Using the wrong parameter name (case-sensitive) will result in null or errors.
• Not providing a default value means the input box starts empty, which might confuse users.
• Trying to use parameters outside the pipeline block or before they are defined will fail.

groovy

pipeline {
  agent any
  stages {
    stage('Fail Example') {
      steps {
        // This will fail because parameters block is missing
        echo "Value: ${params.MY_PARAM}"
      }
    }
  }
}

// Correct way:
pipeline {
  agent any
  parameters {
    string(name: 'MY_PARAM', defaultValue: 'default', description: 'A parameter')
  }
  stages {
    stage('Success Example') {
      steps {
        echo "Value: ${params.MY_PARAM}"
      }
    }
  }
}

Quick Reference

Use this cheat sheet to quickly define and use string parameters in Jenkins pipelines:

Concept	Usage	Description
Define string parameter	string(name: 'PARAM', defaultValue: 'val', description: 'desc')	Creates a text input parameter
Access parameter	params.PARAM	Gets the value entered by the user
Default value	defaultValue: 'val'	Pre-fills the input box
Description	description: 'desc'	Explains the parameter purpose

Key Takeaways

Always define string parameters inside the pipeline's parameters block.

Access string parameters using params.PARAM_NAME inside your pipeline script.

Provide default values to guide users and avoid empty inputs.

Parameter names are case-sensitive and must match when accessed.

Without defining parameters, params.PARAM_NAME will be empty or cause errors.