Parameterized builds in Jenkins - Commands & Configuration

Introduction

Sometimes you want to run the same Jenkins job but with different inputs each time. Parameterized builds let you give values like names or versions when you start the job, so it can behave differently without changing the job itself.

When you want to build the same project but for different environments like testing or production.

When you need to pass a version number or feature flag to your build without editing the job.

When you want to run a deployment job with different server addresses each time.

When you want to trigger a job manually and choose options like debug mode or release mode.

When you want to reuse one job for multiple similar tasks by changing parameters.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  parameters {
    string(name: 'BRANCH_NAME', defaultValue: 'main', description: 'Git branch to build')
    booleanParam(name: 'RUN_TESTS', defaultValue: true, description: 'Run tests after build')
  }
  stages {
    stage('Checkout') {
      steps {
        echo "Checking out branch ${params.BRANCH_NAME}"
        git branch: "${params.BRANCH_NAME}", url: 'https://github.com/example/my-app.git'
      }
    }
    stage('Build') {
      steps {
        echo 'Building the project'
      }
    }
    stage('Test') {
      when {
        expression { return params.RUN_TESTS }
      }
      steps {
        echo 'Running tests'
      }
    }
  }
}

This Jenkinsfile defines a pipeline with two parameters: BRANCH_NAME to choose which Git branch to build, and RUN_TESTS to decide if tests should run.

The Checkout stage uses the branch parameter to get the right code. The Test stage runs only if RUN_TESTS is true.

Commands

This command starts the Jenkins job named 'my-pipeline' and sets the parameter BRANCH_NAME to 'feature-xyz' and RUN_TESTS to false, so it builds that branch and skips tests.

Terminal

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

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Checking out branch feature-xyz

[Pipeline] git

Cloning repository https://github.com/example/my-app.git

[Pipeline] echo

Building the project

[Pipeline] End of Pipeline

Finished: SUCCESS

→

-p BRANCH_NAME=feature-xyz - Sets the Git branch to build

→

-p RUN_TESTS=false - Disables running tests

This command runs the same job but builds the main branch and runs tests because RUN_TESTS is true.

Terminal

jenkins-jobs build my-pipeline -p BRANCH_NAME=main -p RUN_TESTS=true

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] echo

Checking out branch main

[Pipeline] git

Cloning repository https://github.com/example/my-app.git

[Pipeline] echo

Building the project

[Pipeline] echo

Running tests

[Pipeline] End of Pipeline

Finished: SUCCESS

→

-p BRANCH_NAME=main - Sets the Git branch to build

→

-p RUN_TESTS=true - Enables running tests

Key Concept

If you remember nothing else from parameterized builds, remember: parameters let you change what a Jenkins job does each time you run it without changing the job itself.

Common Mistakes

Not defining parameters in the Jenkinsfile but trying to pass them when running the job

Jenkins won't recognize parameters that are not declared, so the job ignores them or fails.

Always declare all parameters inside the Jenkinsfile under the parameters block before using them.

Passing parameters with wrong names or typos in the command line

Jenkins will not match the parameter and will use default values or error out.

Double-check parameter names exactly as declared in the Jenkinsfile when passing them.

Using parameters but not referencing them in the pipeline steps

Parameters have no effect if the pipeline code does not use them, so the build behaves the same every time.

Use parameters with the syntax params.PARAMETER_NAME inside the Jenkinsfile to control behavior.

Summary

Define parameters in the Jenkinsfile to let users provide inputs when starting a build.

Use the params object inside pipeline steps to access parameter values.

Run the job with the jenkins-jobs CLI and pass parameters with -p flags to customize each build.