DEV Community

Janak Shrestha
Janak Shrestha

Posted on

Jenkins Parameterized Builds

#jenkins

A new DevOps Engineer has joined the team and he will be assigned some Jenkins related tasks. Before that, the team wanted to test a simple parameterized job to understand basic functionality of parameterized builds. He is given a simple parameterized job to build in Jenkins. Please find more details below:

Click on the Jenkins button on the top bar to access the Jenkins UI. Login using username admin and password Adm!n321.

  1. Create a parameterized job which should be named as parameterized-job
  2. Add a string parameter named Stage; its default value should be Build.
  3. Add a choice parameter named env; its choices should be Development, Staging and Production.
  4. Configure job to execute a shell command, which should echo both parameter values (you are passing in the job).
  5. Build the Jenkins job at least once with choice parameter value Development to make sure it passes. Note:
  6. You might need to install some plugins and restart Jenkins service. So, we recommend clicking on Restart Jenkins when installation is complete and no jobs are running on plugin installation/update page i.e update centre. Also, Jenkins UI sometimes gets stuck when Jenkins service restarts in the back end. In this case, please make sure to refresh the UI page.
  7. For these kind of scenarios requiring changes to be done in a web UI, please take screenshots so that you can share it with us for review in case your task is marked incomplete. You may also consider using a screen recording software such as loom.com to record and share your work.

Step 1: Access the Jenkins UI

Click the Jenkins button on the top bar of your KodeKloud lab environment. This opens the Jenkins UI in a new tab.

Log in with:

Field Value
Username admin
Password Adm!n321

You'll land on the Jenkins dashboard.

Step 2: Create the Job

From the dashboard:

  1. Click New Item in the left sidebar
  2. In the Enter an item name field, type: parameterized-job
  3. Select Freestyle project
  4. Click OK

You'll be taken to the job configuration page.

Step 3: Enable Parameterized Build

At the top of the configuration page, in the General section:

  1. Check the box: ☑️ This project is parameterized

Once checked, an Add Parameter dropdown button will appear. This is where we'll define our parameters.

Step 4: Add the String Parameter (Stage)

  1. Click Add Parameter → select String Parameter
  2. Fill in the fields:
Field Value
Name Stage
Default Value Build
Description (optional) Enter the stage name

What is a String Parameter?
It accepts free-form text input. You can set a default value that pre-fills the input box when a user runs the job.

Step 5: Add the Choice Parameter (env)

  1. Click Add Parameter again → select Choice Parameter
  2. Fill in the fields:
Field Value
Name env
Choices See below
Description (optional) Select the environment

For the Choices field, enter each option on its own line:

Development
Staging
Production
Enter fullscreen mode Exit fullscreen mode

⚠️ Important: Do NOT use commas. Each choice must be on a separate line. Jenkins will parse them into a dropdown list. The order matters — Development should be first so it appears at the top.

What is a Choice Parameter?
It presents a dropdown of predefined options. Users pick one; no free-text input is allowed.

Final Parameter Order

Your configuration should show:

Parameters:
├── Stage (String)  → default: "Build"
└── env   (Choice)  → Development | Staging | Production
Enter fullscreen mode Exit fullscreen mode

Step 6: Configure the Shell Command

Scroll down to the Build section:

  1. Click Add build step → select Execute shell
  2. In the Command text area, enter: 
echo "Stage: $Stage"
echo "Environment: $env"
Enter fullscreen mode Exit fullscreen mode

How Parameter Injection Works

Jenkins exposes parameters as environment variables during the build. So $Stage and $env are available just like any shell variable. The syntax is case-sensitive — $env won't match $ENV or $Env.

Step 7: Save the Job

  1. Click Save at the bottom of the page
  2. You'll be redirected to the job page

The job page will now show a Build with Parameters option in the left sidebar (instead of just "Build Now").

Step 8: Build with Parameters

  1. Click Build with Parameters in the left sidebar
  2. You'll see a form:
    • Stage: text field pre-filled with Build
    • env: dropdown with Development, Staging, Production
  3. Select Development from the env dropdown
  4. Leave Stage as Build (the default)
  5. Click Build

Step 9: Verify the Build Output

In the left sidebar, Build History will show #1 appear. Click on #1 → Console Output.

You should see:

Started by user admin
Running as SYSTEM
Building in workspace /var/lib/jenkins/workspace/parameterized-job
[parameterized-job] $ /bin/sh -xe /tmp/jenkins4687125526416196371.sh
+ echo Stage: Build
Stage: Build
+ echo Environment: Development
Environment: Development
Finished: SUCCESS
Enter fullscreen mode Exit fullscreen mode

Reading the Output

Line Meaning
+ echo Stage: Build Shell command Jenkins executed
Stage: Build The string parameter value printed
+ echo Environment: Development Second shell command
Environment: Development The choice parameter value printed
Finished: SUCCESS Build completed without errors

The + prefix is the shell's trace mode (sh -x), which Jenkins enables by default to show every command it runs. It's incredibly useful for debugging.

Troubleshooting

Issue Solution
"Add Parameter" button missing Make sure This project is parameterized is checked
Choice parameter only shows one option Each choice must be on a separate line, not comma-separated
$Stage prints empty Variable name must match exactly — Jenkins is case-sensitive
"Build with Parameters" not visible Refresh the job page; ensure parameters were saved correctly
Build fails Read the Console Output — the + lines show exactly what ran

Summary

# Task Result
1 Created parameterized-job Freestyle project ✅
2 Added String Parameter Stage Default: Build ✅
3 Added Choice Parameter env Development / Staging / Production ✅
4 Configured shell command Echoed both values ✅
5 Built with env = Development Build #1 SUCCESS ✅

Key Takeaways

  1. Parameterized builds eliminate job duplication. One job, many configurations — perfect for multi-environment deployments.
  2. String vs. Choice has a clear purpose. Use String for free-text input with a sensible default; use Choice to constrain input to valid options.
  3. Parameters become environment variables. Any script step can reference them via $NAME.
  4. Order matters in the UI. The order you add parameters is the order users see them in the "Build with Parameters" form.
  5. The Console Output is your best friend. The + lines reveal exactly what Jenkins executed — invaluable when debugging.

Real-World Applications

This simple pattern scales into serious CI/CD workflows:

  • Deploy to a specific environment: Choice parameter for env, then use it in a deployment script
  • Build a specific branch: String parameter for BRANCH, then git checkout $BRANCH
  • Run with configurable versions: String parameter for VERSION, then docker build -t app:$VERSION
  • Release channels: Choice parameter for CHANNEL (stable/beta/nightly)

Once you're comfortable with parameters, the next step is chaining jobs together with the Parameterized Trigger plugin — but that's a topic for another blog.

Top comments (0)