Parameters block declaration in Jenkins - Commands & Configuration

Introduction

Sometimes you want to run a Jenkins job but change some values each time, like which branch to build or what version to deploy. The parameters block lets you ask for these values before the job starts.

When you want to choose which branch of your code to build each time you run the job

When you need to specify a version number or tag for deployment dynamically

When you want to toggle features on or off during a build without changing the code

When you want to input a custom message or label for the build

When you want to select options from a list before starting the job

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  parameters {
    string(name: 'BRANCH_NAME', defaultValue: 'main', description: 'Branch to build')
    booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run unit tests')
    choice(name: 'DEPLOY_ENV', choices: ['dev', 'staging', 'production'], description: 'Select deployment environment')
  }
  stages {
    stage('Build') {
      steps {
        echo "Building branch: ${params.BRANCH_NAME}"
      }
    }
    stage('Test') {
      when {
        expression { return params.RUN_TESTS }
      }
      steps {
        echo 'Running tests...'
      }
    }
    stage('Deploy') {
      steps {
        echo "Deploying to environment: ${params.DEPLOY_ENV}"
      }
    }
  }
}

This Jenkinsfile defines a parameters block inside the pipeline. It declares three parameters:

• string: lets the user enter text, here for the branch name with a default of 'main'.
• booleanParam: a checkbox to decide if tests should run, default true.
• choice: a dropdown list to pick the deployment environment.

These parameters can be accessed in the pipeline using params.PARAMETER_NAME.

Commands

This command updates the Jenkins job with the new Jenkinsfile that includes the parameters block. It makes Jenkins aware of the parameters to ask before running the job.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully: Jenkinsfile

This command starts the Jenkins pipeline named 'my-pipeline' and passes values for the parameters declared in the Jenkinsfile. It overrides the defaults with specific values for this run.

Terminal

jenkins build my-pipeline -p BRANCH_NAME=feature-xyz -p RUN_TESTS=false -p DEPLOY_ENV=staging

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Building branch: feature-xyz

[Pipeline] script

[Pipeline] echo

Running tests...

[Pipeline] echo

Deploying to environment: staging

[Pipeline] End of Pipeline

→

-p - Pass a parameter value to the Jenkins job

This command runs the Jenkins pipeline without passing parameters, so it uses the default values defined in the parameters block.

Terminal

jenkins build my-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Building branch: main

[Pipeline] script

[Pipeline] echo

Running tests...

[Pipeline] echo

Deploying to environment: dev

[Pipeline] End of Pipeline

Key Concept

If you remember nothing else from this pattern, remember: the parameters block lets you ask for input values before the Jenkins job runs, making your builds flexible and reusable.

Common Mistakes

Forgetting to use 'params.' prefix when accessing parameter values inside the pipeline

Jenkins won't recognize the parameter and will cause errors or empty values

Always use 'params.PARAMETER_NAME' to access the parameter values in your pipeline script

Not defining default values for parameters

If you run the job without passing parameters, Jenkins will fail or ask for input every time

Always provide sensible default values in the parameters block to allow smooth runs

Passing parameters with wrong names or types when triggering the job

Jenkins will ignore or error out because the parameter does not exist or is invalid

Use exact parameter names and correct types as declared in the Jenkinsfile when triggering builds

Summary

The parameters block in Jenkinsfile declares inputs users can provide before running a job.

You can define string, boolean, choice, and other parameter types with default values and descriptions.

Access parameters inside the pipeline using 'params.PARAMETER_NAME' to customize build behavior.