Fix incorrect guidance that agent JVM must match controller JVM version#8870
Open
devs6186 wants to merge 1 commit intojenkins-infra:masterfrom
Open
Fix incorrect guidance that agent JVM must match controller JVM version#8870devs6186 wants to merge 1 commit intojenkins-infra:masterfrom
devs6186 wants to merge 1 commit intojenkins-infra:masterfrom
Conversation
Three upgrade guides stated that agents must run the same JVM version as the controller. This is inaccurate: agents only need to satisfy the minimum Java version required by the Jenkins version running on the controller. They do not need to match the controller's exact (or major) version, although running the same major version reduces the risk of serialization incompatibilities. Update the "JVM version on agents" sections in all three Java upgrade guides (Java 11, 17, and 21) with the corrected language. Also clarify the description of the checkNodes diagnostic script in the Java 21 guide. Fixes jenkins-infra#8691
probot-autolabeler
bot
added
the
documentation
krisstern
reviewed
Feb 24, 2026
Comment on lines
+32
to
+35
| The `checkNodes` script determines what version of Java is running the controller process, along with the version of Java on each connected agent. | ||
| When the agent Java version matches the controller Java version, the result shows `OK`. | ||
| Otherwise, the result displays the controller Java version and the version found on the agent. | ||
| Use this script to identify agents that may need a Java upgrade. |
Member
There was a problem hiding this comment.
Why are these changes needed in this PR?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three Java upgrade guides incorrectly stated that agents must run the same JVM version as the controller. This is inaccurate: agents only need to satisfy the minimum Java version required by the running Jenkins version. They do not need to match the controller's exact major version, though running the same major version reduces serialization risks.
Motivation / Issue
Closes #8691
Changes Made
content/doc/book/platform-information/upgrade-java-to-11.adoc: Updated the "JVM version on agents" section to replace "must run the same JVM version" with the correct minimum-version requirement language.content/doc/book/platform-information/upgrade-java-to-17.adoc: Same correction applied.content/doc/book/platform-information/upgrade-java-to-21.adoc: Same correction applied. Also clarified the description of thecheckNodesdiagnostic script, which checks version parity but whose output does not imply agents are required to match exactly.Testing / Verification
make checkpasses with no errorsmake generatecompletes successfullymake run— updated sections verified at http://localhost:4242/doc/book/platform-information/upgrade-java-to-11/Notes for Reviewers
The fix is based on the analysis in issue #8691 by @daniel-beck (Jenkins maintainer) and the CloudBees CI documentation. The added note about same-major-version being recommended reflects the nuanced comment by @jtnord in the issue thread about serialization risks.