How to Upgrade Jenkins Without Breaking Pipelines

Jenkins LTS vs Weekly Releases

Jenkins ships two release lines. The LTS release line page says the community picks a new LTS baseline every 12 weeks and publishes three updates for it in four-week cycles, and that the line "only receives important bug and security related fixes."

That rhythm makes LTS the line to upgrade on for a shared controller, with one version change about every four weeks and an upgrade guide for each new line.

When you switch lines, the same LTS page asks for this:

• Weekly to LTS - pick an LTS baseline that is numerically newer than your weekly version, so a controller on weekly 2.590 waits for an LTS line based on 2.590 or later.
• LTS to weekly - move to a weekly release published after your LTS version; the page recommends the most recent one.

Upgrading on this schedule is part of the hosting cost weighed in GitHub Actions vs Jenkins. The rest of this guide assumes you are staying on Jenkins and moving LTS to LTS.

Read Every Jenkins LTS Upgrade Guide on Your Path

Each LTS upgrade guide covers the jump from the previous LTS line, and the index recommends reading the sections for every release in between when you skip LTS releases. From 2.541.3, the path to 2.580.2 crosses the 2.555, 2.568 and 2.580 lines, and their notes hold these changes that can stop a controller or a pipeline:

The crumbIssuer row is the one that can stop the controller outright. The 2.555 upgrade guide says the Configuration as Code plugin cancels Jenkins startup when it finds a deprecated section, so a leftover block like this one stops 2.555.1 from processing any jobs:

jenkins:
  crumbIssuer:
    standard:
      excludeClientIPFromCrumb: false

Delete the block before you upgrade. The same guide documents configuration-as-code: deprecated: warn, which logs a warning instead of cancelling startup, but it also notes that the warning mode may not handle every configuration change.

Package installs older than 2.541.1 have one more step. The 2026 repository signing keys announcement says apt can report NO_PUBKEY 7198F4B714ABFC68 until you install the jenkins.io-2026.key file for your repository.

Move Jenkins and Its Agents to Java 21 or 25 First

Change Java before you change Jenkins, on the version you already run. The 2.555 guide calls it "critical to upgrade both the controller and agents to Java 21 or Java 25 prior to upgrading Jenkins to 2.555.1," and the Jenkins Java support policy applies the requirement to the controller, every type of agent and CLI clients:

• Java 25 - supported since LTS 2.541.1, with planned end of support in September 2029.
• Java 21 - supported since LTS 2.479.1, with planned end of support in September 2027.
• Java 17 - unsupported now; 2.541.3, from March 2026, was its final LTS release.

Because 2.541.3 already runs on Java 21, you can move Java in one maintenance window and the core in the next, and a failed core upgrade later rolls back without touching Java. The Java 21 upgrade guide stops Jenkins, installs Java, switches the system default and restarts; with the distribution packages the Jenkins Linux install page uses, that looks like this:

sudo systemctl stop jenkins

# Debian and Ubuntu
sudo apt install fontconfig openjdk-21-jre
sudo update-alternatives --config java

# Red Hat Enterprise Linux and derivatives
sudo yum install fontconfig java-21-openjdk
sudo alternatives --config java

java -version
sudo systemctl restart jenkins

If you would rather not change the system default, the same guide says to run systemctl edit jenkins and set JAVA_HOME or JENKINS_JAVA_CMD for the service. Confirm the result under Manage Jenkins > System Information before you go further.

Agents can run a different Java release from the controller as long as it meets the controller's minimum, and the Java 21 guide points to the Versions Node Monitors plugin, which shows each agent's Java version and can disconnect agents that run an unsupported one. A job that still compiles with Java 17 keeps working, because the 2.555 guide separates the JVM that runs the agent process from the JDK your build uses. The Java support policy names one exception: the Maven Integration plugin needs the JDK of a Maven build to be at least the Java version the controller runs, so check those jobs on the staging copy.

On Docker, change only the Java part of the tag first: jenkins/jenkins:2.541.3-lts-jdk21 is the same Jenkins on Java 21, published on March 18, 2026 next to the jdk17 image.

Check Plugin Compatibility Before You Upgrade Jenkins

A Jenkins controller asks the update center for plugins that match its own core version, and the update center forwards the request to a tiered site that, in the words of its layout notes, will "only offer plugins compatible with the respective baseline."

That is why the 2.555 guide asks for plugin updates "both before and after upgrading": before, you get the newest releases your current core can load, and after, you get the releases that need the new one. A short script shows you both lists before the maintenance window.

Jenkins.get().pluginManager.plugins
  .collect { it.shortName + ":" + it.version }
  .sort()
  .each { println it }

// upgrade-check.mjs: check plugins.txt against the update center
// for your current LTS and your target LTS (Node.js 18 or newer).
// Usage: node upgrade-check.mjs plugins.txt 2.541.3 2.580.2
import { readFileSync } from "node:fs";

const [file, fromCore, toCore] = process.argv.slice(2);

async function updateCenter(core) {
  const base = "https://updates.jenkins.io/update-center.actual.json";
  const res = await fetch(base + "?version=" + core);
  if (!res.ok) throw new Error(core + ": HTTP " + res.status);
  return res.json();
}

const [from, to] = await Promise.all([updateCenter(fromCore), updateCenter(toCore)]);

const installed = readFileSync(file, "utf8").split(/\r?\n/)
  .map((line) => line.replace(/#.*/, "").trim())
  .filter(Boolean)
  .map((line) => line.split(":"));

function warned(id, version) {
  return to.warnings.some((w) => w.type === "plugin" && w.name === id &&
    w.versions.some((v) => new RegExp("^(?:" + v.pattern + ")$").test(version)));
}

console.log(fromCore + " to " + toCore + ", update center " + to.generationTimestamp);
for (const [id, version] of installed) {
  const now = from.plugins[id];
  const next = to.plugins[id];
  const notes = [];
  if (!next) notes.push("not offered for " + toCore);
  if (next && ((next.labels || []).includes("deprecated") || to.deprecations[id])) notes.push("deprecated");
  if (warned(id, version)) notes.push("security warning on " + version);
  if (now && now.version !== version) notes.push("update now to " + now.version);
  if (now && next && next.version !== now.version) {
    notes.push("after upgrade: " + next.version + " (needs " + next.requiredCore + ")");
  }
  console.log(id + (notes.length ? "" : ": ok"));
  for (const note of notes) console.log("  " + note);
}

workflow-aggregator:608.v67378e9d3db_1
workflow-job:1571.1585.v21fce07cd04d
workflow-cps:4400.v300cf4f6cef5
git:5.11.0
credentials:1511.v2e3cb_0008ef0
credentials-binding:728.v902a_273b_8947
junit:1446.veeff2ec8581c
docker-workflow:653.v2f2c08eff0ec
configuration-as-code:2147.v8a_8d38668c72
role-strategy:867.vd09254229f9b_
coverage:2.3139.v731d2e83ea_8a_
warnings-ng:13.10085.v94a_d6ca_82b_f6
blueocean:1.27.26
lambdatest-automation:1.22.0

2.541.3 to 2.580.2, update center 2026-11-11T15:24:22Z
workflow-aggregator: ok
workflow-job
  after upgrade: 1624.ve973eb_34e031 (needs 2.568.1)
workflow-cps
  after upgrade: 4403.v471713a_cea_19 (needs 2.568.1)
git: ok
credentials
  after upgrade: 1514.vb_01eb_014e7d4 (needs 2.555.3)
credentials-binding: ok
junit
  after upgrade: 1458.v38661c0638e2 (needs 2.555.3)
docker-workflow: ok
configuration-as-code: ok
role-strategy
  after upgrade: 928.vc60b_edb_fea_e1 (needs 2.568.3)
coverage
  security warning on 2.3139.v731d2e83ea_8a_
  after upgrade: 4.3567.v34a_294650f39 (needs 2.555.3)
warnings-ng
  security warning on 13.10085.v94a_d6ca_82b_f6
  after upgrade: 13.10345.v6642ea_283a_ef (needs 2.555.3)
blueocean
  deprecated
lambdatest-automation: ok

Back Up JENKINS_HOME Before You Upgrade Jenkins

Take the backup after the old version stops and before the new one starts, so the copy matches what the old core wrote. Drain the controller first with Prepare for Shutdown, which the Manage Jenkins documentation says "prevents new builds from starting so that the system can be shut down safely," then let running builds finish and stop the service.

The Jenkins backup guide says filesystem snapshots give the most consistent copy, and that the plugins/*.jpi and plugins/*.hpi files are the plugin packages at the versions you run. Keep these for the rollback:

• JENKINS_HOME - a snapshot or a full copy of the stopped controller's home directory.
• master.key - stored apart from that copy, because the backup guide says never to include the controller key in the backup itself.
• The old core - the package version number, the previous jenkins.war or the exact Docker tag, such as 2.541.3-lts-jdk21.
• plugins.txt - the list you exported, so you can compare plugin versions after the upgrade.

Test the backup before you trust it: the guide restores it into a temporary directory, points JENKINS_HOME there and starts Jenkins on another port with --httpPort=9999. The rest of the routine, including what a missing secrets folder does to stored credentials, is covered in these Jenkins best practices.

Rehearse the Jenkins Upgrade on a Restored Copy

That test restore is also your staging controller. It carries the same jobs, credentials and triggers as production, so cut its route to anything it deploys to or notifies before you start it, then run the whole upgrade on it:

• Start the copy on 2.541.3 and Java 21, and confirm that every job and plugin loads.
• Install every update listed under Plugins > Updates, then restart.
• Delete the crumbIssuer block from the Configuration as Code YAML, if you use it.
• On an air-gapped copy, place the nine plugins that 2.580.1 no longer bundles in JENKINS_HOME/plugins before the new version starts.
• Upgrade the core to 2.580.2 the way production will: package, WAR file or image tag.
• Update plugins again, restart, and run the canary pipeline described below.

Time each step, because the total is the maintenance window to announce for production. Write down every change you make along the way, such as a plugin removed or a YAML key deleted, so you can repeat each edit on production.

Upgrade Jenkins on the Production Controller

Production follows the rehearsal: Prepare for Shutdown, wait for running builds, take the final backup, then upgrade with the same method you tested.

sudo apt update
sudo apt install jenkins=2.580.2
sudo apt-mark hold jenkins

sudo dnf upgrade jenkins-2.580.2

curl -fLO https://get.jenkins.io/war-stable/2.580.2/jenkins.war
curl -fL https://get.jenkins.io/war-stable/2.580.2/jenkins.war.sha256
sha256sum jenkins.war

docker stop jenkins && docker rm jenkins
docker run -d --name jenkins --restart=on-failure \
  -p 8080:8080 -p 50000:50000 \
  -v jenkins_home:/var/jenkins_home \
  jenkins/jenkins:2.580.2-lts-jdk21

Once the controller is up, confirm the version under Manage Jenkins > About Jenkins. The plugin management docs say Jenkins checks the update center once every 24 hours by default, so click Check now on the Updates tab, install what the new core unlocks and restart through /safeRestart.

Run a Canary Pipeline After the Jenkins Upgrade

A clean startup shows that the core and plugins load. To prove a build still works, run one Pipeline that checks out code, reads a credential and publishes results on the agent label your real jobs use, before you open the queue; this Jenkins pipeline tutorial covers the Declarative syntax if you need it. Jobs that start containers in their tests also need Docker access on the agent, which the Testcontainers CI guide covers for Jenkins.

pipeline {
  agent { label 'linux' }
  environment {
    LT_USERNAME   = credentials('lt-username')
    LT_ACCESS_KEY = credentials('lt-access-key')
  }
  stages {
    stage('Checkout') {
      steps { checkout scm }
    }
    stage('Tests on HyperExecute') {
      steps {
        sh '''
          curl -O https://downloads.lambdatest.com/hyperexecute/linux/hyperexecute
          chmod +x hyperexecute
          ./hyperexecute --config hyperexecute.yaml --download-artifacts
        '''
      }
    }
  }
  post {
    always {
      // Point this at the JUnit XML your hyperexecute.yaml uploads
      junit testResults: '**/TEST-*.xml'
    }
  }
}

The test stage is the part of the canary you want to depend on the fewest plugins. HyperExecute from TestMu AI wires into Jenkins through a plain shell step rather than a plugin: the job downloads the CLI, which reads LT_USERNAME and LT_ACCESS_KEY from the environment, runs your hyperexecute.yaml, and --download-artifacts brings the reports back for the junit step.

Store both values as Secret text credentials: the environment block hands them to the sh step as variables, and the Jenkins Pipeline documentation says Jenkins masks such values in build output. If your jobs load Jenkins shared libraries, add a stage that loads yours too, because library code runs on the Pipeline plugins you just updated.

While the canary runs, check the controller itself:

• Plugins Failed To Load - Jenkins core raises this warning on the Manage Jenkins page when a plugin cannot start, for example because it needs a newer core. After a clean upgrade, there is none.
• Agent Java versions - the Versions Node Monitors plugin shows the Java version of every agent; any agent below Java 21 has to move before it can run builds for the new core.
• TestMu AI report - on a job that uses the TestMu AI Jenkins plugin, open a build and confirm the TestMu AI Report icon still sits in the build's left menu, as the plugin documentation shows.
• Manage Old Data - leave it alone for now. Its page text in Jenkins core says data is migrated when loaded but not resaved, which is what keeps a downgrade possible.

Note: If your rehearsal controller tests apps that are not on the public internet, the TestMu AI Jenkins plugin sets up and tears down the tunnel binary for each job, so browser tests on the TestMu AI grid can still reach them. To try it, start free.

How to Roll Back a Jenkins Upgrade

Roll back when the controller will not start, when a plugin you depend on sits in Plugins Failed To Load, or when the canary fails and the fix will not fit in the window. Restore the backup instead of reinstalling the old core over the upgraded home, because the upgraded home holds plugins and data the old core cannot use:

• Plugins built for the new core - after the upgrade you installed releases such as workflow-job 1624.ve973eb_34e031, which needs 2.568.1. Put 2.541.3 under it and Jenkins rejects the plugin with the message "Jenkins (2.568.1) or higher required," built from a template in Jenkins core's messages file.
• Data the new version saved - the Manage Old Data page warns that creating and configuring jobs and running builds can save data that older Jenkins or plugin versions cannot read.

For a package install, the rollback looks like this:

sudo systemctl stop jenkins
# Restore JENKINS_HOME and master.key from the backup first

# Debian and Ubuntu: apt asks you to confirm the downgrade
sudo apt-mark unhold jenkins
sudo apt install jenkins=2.541.3
sudo apt-mark hold jenkins

# Red Hat Enterprise Linux and derivatives
sudo dnf downgrade jenkins-2.541.3

sudo systemctl start jenkins

For a WAR install, put the saved jenkins.war back. For Docker, restore the jenkins_home volume from the backup and start the previous tag, such as jenkins/jenkins:2.541.3-lts-jdk21; Java stays on 21 in every case, because 2.541.3 supports it.

Builds that ran between the upgrade and the rollback are not in the restored home, so copy out any artifacts or test results you need before you restore. Then run the canary on the old version to confirm the rollback, and keep the plugin check output, which lists what to fix before the next attempt.

Conclusion

Before you upgrade Jenkins again, run the plugin check: export your plugin list today and run it from your current LTS to 2.580.2, because it shows how much of the upgrade is plugin work and whether you hold security fixes your core cannot install. Then plan Java, the rehearsal and the production cutover as separate windows, and keep the pre-upgrade backup until the canary passes on the new version.

For the test stage of that canary, the HyperExecute Jenkins integration guide shows the shell-step setup used above, so the stage that proves each upgrade runs your suite on TestMu AI without another plugin on the controller.