Upgrading to Jenkins LTS 2.555.x

Each section covers the upgrade from the previous LTS release, the section on 2.555.1 covers the upgrade from 2.541.3.

Upgrading to Jenkins 2.555.2

MSI Installer Signing Certificate

Beginning with Jenkins LTS 2.555.2 and Jenkins weekly 2.562, the Jenkins MSI installer is signed by "LF Open Source, LLC" using the Microsoft Artifact Signing Service.

The change may cause the Edge browser on Windows to report that the file is not commonly downloaded. Users need to select "Keep anyway" to download the installer.

When running the Jenkins MSI installer with the new signature, Windows SmartScreen may report:

Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.

— Microsoft Defender SmartScreen

Users need to select "More info" to advance to the next screen and then select "Run anyway".

A blog post provides screenshots and more details.

The Microsoft support forum says that Microsoft SmartScreen will stop prompting users once there are enough installations to increase its reputation score.

Upgrading to Jenkins 2.555.1

Require Java 21

Beginning with Jenkins 2.555.1, Jenkins requires Java 21 or Java 25 on both the controller JVM and agent JVMs.

Therefore, it is critical to upgrade both the controller and agents to Java 21 or Java 25 prior to upgrading Jenkins to 2.555.1. Use the Versions Node Monitors plugin to verify that agents are running a compatible version of Java. In addition to upgrading your controller and agents, you must ensure that all plugins have been updated both before and after upgrading. This ensures up-to-date plugins that remain compatible. If plugins are not updated both before and after the upgrade, compatibility issues may arise.

The official Jenkins Docker images for the controller and agents have been based on Java 21 for several months, while also supporting Java 25 as an alternative. With the release of Jenkins 2.555.1, the Java 17 images have been retired. Users of the official Docker images do not need to install or configure Java on their own, as it comes preinstalled in the Docker images.

If your application build still requires Java 8, 11, or 17, and you are using a Docker image to run the agent Java process remoting.jar simultaneously, you must provide a Java 21 or Java 25 runtime for the Jenkins agent process and a Java 8, 11, or 17 environment for your application build.

Users of the official Jenkins OS packages for Debian, Red Hat, and SUSE Linux distributions must use their own Java package. These users may install Java 21 or Java 25 from their Linux distribution, as described on the package download site:

The above downloads do not require any custom repositories, so this is the simplest method, and has been tested by the Jenkins project. However, the above method does not give the user a high degree of control over the Java runtime environment. The official Jenkins Docker images and the Jenkins infrastructure project use Eclipse Temurin ®. Enthusiastic users can install Java from Eclipse Temurin or another vendor. Eclipse Temurin provides Linux installation packages, as described in a blog post by George Adams. The choice of Java vendor is up to you, as long as that vendor provides Java 21 or Java 25. Refer to your chosen Java vendor for installation instructions.

Once you have installed a suitable version of Java, configure Jenkins to use that Java runtime. The most straightforward way is to configure that version of Java as the default version, at the operating system (OS) level:

Debian: update-alternatives --config java
Red Hat: alternatives --config java
SUSE: update-alternatives --config java

Alternatively, users who do not wish to change the default version of Java can customize the JAVA_HOME or JENKINS_JAVA_CMD environment variable as part of the Jenkins systemd(1) service unit. Refer to the Managing systemd services documentation for more information.

If you are using the Environment Injector plugin and receive a WARNING: An illegal reflective access operation has occurred message, there are two workarounds for affected users:

If you only need to update an existing environment variable (such as PATH), but do not need to add or remove environment variables, upgrade to version 2.919.v009a_a_1067cd0 of the Environment Injector plugin.

If you need to add (set) or remove (unset) environment variables, consider unchecking Prepare jobs environment or Unset System Environment Variables in the Environment Injector plugin, to reduce or eliminate usage of this plugin.. Instead, implement by starting the agent process (the process started by running java -jar agent.jar […) in the desired environment (clearing the environment and defining FOO with env - FOO=BAR java -jar agent.jar […) in your shell. Mutating environment variables in a Unix process can be problematic, so it is recommended that you start the process with the desired environment, rather than changing the environment later. Changing the environment after a Unix process has started often results in race conditions, and the Environment Injector plugin is no exception.

If you need to add (set) or remove (unset) environment variables and must do this using the Environment Injector plugin, then use Java 21 for the controller and the agents and specify the --add-opens JVM option for your agent:

For outbound agents that connect via SSH, you must specify the JVM options on the agent configuration page:

Specifying the JVM options for your agent that connects via SSH.

For inbound agents, you must also add the argument to the JVM on the agent configuration page. For example:

java --add-opens java.base/java.lang=ALL-UNNAMED --add-
opens=java.base/java.lang.reflect=ALL-UNNAMED -jar agent.jar -url
http://localhost:9090/ -secret <secret> -name inbound -workDir <workdir>

Removing IP address from DefaultCrumbIssuer

The IP address is no longer included in the default crumb issuer that provides Cross-Site Request Forgery (CSRF or XSRF) protection. Jenkins already uses the session ID to compute CSRF crumbs. Using the session id to compute the crumb makes usage of the client ip unnecessary.

Jenkins administrators that use configuration as code should remove the crumbIssuer section from their configuration before upgrading to Jenkins 2.555.1.

  crumbIssuer:
    standard:
      excludeClientIPFromCrumb: false

By default, the Configuration as Code Plugin cancels Jenkins startup when a deprecated section is detected. If the crumbIssuer section is in a Jenkins 2.555.1 global configuration, Jenkins 2.555.1 will cancel startup and process no jobs. That is the intentional behavior of the plugin so that administrators detect and apply configuration changes immediately.

The Configuration as Code Plugin can warn when deprecated configuration elements are found instead of canceling startup. Warning on deprecated configuration elements may not handle all configuration changes. If an administrator wants a warning for configuration as code deprecations instead of canceling startup, they can add the following to their configuration as code global configuration:

configuration-as-code:
  deprecated: warn

User Handbook