SchimmelDevNest

Programming

Changing Jenkins build number

27 September 2026 · 4 min read

Changing Jenkins build number

In the fast-paced world of continuous integration and continuous delivery (CI/CD), Jenkins stands as a cornerstone for automating software development processes. A critical yet often overlooked aspect of effective CI/CD is robust build number management. While Jenkins automatically assigns sequential build numbers, there are numerous scenarios where developers and operations teams need finer control. Whether it’s to align with a specific release strategy, recover from a failed build, or streamline development across multiple branches, the ability to modify these identifiers is crucial. This article delves into the various techniques for changing Jenkins build number, exploring both straightforward plugin-based solutions and more advanced scripting methods to ensure your CI/CD pipeline remains flexible and reliable.

Understanding Jenkins Build Numbering

By default, Jenkins assigns a simple, monotonically increasing integer to each build that runs for a specific job. This automatic build numbering starts from 1 and increments by one for every subsequent execution. This sequential approach is straightforward and works well for many projects, providing an immediate chronological order of builds. It helps track the progress and history of a job, making it easy to identify which build is newer or older.

However, relying solely on Jenkins’ default sequential numbering can sometimes limit flexibility, especially in complex release automation workflows or when integrating with external version control systems. For instance, if you have a specific versioning scheme like semantic versioning (e.g., 1.0.0, 1.0.1) that you want to reflect in your build numbers, the default auto-increment might not suffice. Understanding how Jenkins handles these numbers internally is the first step towards effectively customizing them.

The build number is more than just an identifier; it’s a key piece of metadata that can influence deployment, artifact naming, and overall pipeline management. Proper build versioning ensures traceability from source code to deployed artifacts, which is vital for debugging, auditing, and maintaining high-quality software. This is why gaining control over changing Jenkins build number becomes a powerful tool in a DevOps engineer’s arsenal.

Methods for Changing Jenkins Build Number

When the default sequential build numbering isn’t enough, Jenkins offers several powerful ways to customize or reset your build numbers. Each method caters to different needs, ranging from simple resets to highly integrated, programmatic adjustments within your pipeline script. Choosing the right method depends on your project’s complexity and your team’s specific requirements for build versioning and release management.

Method 1: Using the Next Build Number Plugin

The “Next Build Number” plugin is perhaps the most user-friendly way to manually set or reset the build number for a Jenkins job. This plugin is ideal for situations where you need a quick, one-time adjustment, such as after migrating a job, starting a new release cycle, or correcting an accidental build number increment. It provides a simple UI element directly within the job configuration page.

  1. Install the Plugin: Navigate to “Manage Jenkins” > “Manage Plugins” > “Available” tab. Search for “Next Build Number” and install it without restart.
  2. Configure the Job: Go to the specific Jenkins job’s configuration page.
  3. Locate the Option: Scroll down to the “Build Environment” section. You should see a checkbox labeled “Set next build number.”
  4. Enter New Number: Check the box and input your desired next build number (e.g., 100). This number will be used for the very next build that runs.
  5. Save Changes: Save the job configuration. The subsequent build will start with your specified number.

This plugin streamlines the process of changing Jenkins build number without requiring any command-line access or intricate scripting. It’s particularly useful for development teams that prefer GUI-driven solutions for quick adjustments.

Method 2: Scripted Approach (Groovy Script)

For more dynamic or automated control over build numbers, especially within Jenkins Pipelines, using a Groovy script is the most flexible option. This method allows you to programmatically set the next build number based on various conditions, such as extracting version information from your source code (e.g., a pom.xml or package.json file) or integrating with an external version control system’s tags. Groovy scripts can be executed via the Jenkins Script Console or directly within a Pipeline as a build step.

A common pattern involves using the nextBuildNumber property of the current job. For example, to set the next build number to a specific value via the Script Console:

Jenkins.instance.getItemByFullName("Your_Job_Name").updateNextBuildNumber(150)

Within a declarative or scripted pipeline, you can achieve Question & Answer :

Is there a way to change the build number that is sent via email after a job completes? The problem is that are product builds are NOT being done by Jenkins, so we want to be able to get the build number(ie. from a text file) and update the build number in Jenkins to match it. I have tried to set the build number:

set BUILD_NUMBER=45

But the email is still showing the build number that Jenkins originally set.

If you have access to the script console (Manage Jenkins -> Script Console), then you can do this following:

Jenkins.instance.getItemByFullName("YourJobName").updateNextBuildNumber(45)