Standardised Java JDK Management for Jenkins Runners

Refinery Runners for Jenkins: Improved Java Version Support

We are updating the Jenkins Runners aka StackTrack Refinery Runners for Jenkins to improve how Java versions are managed across Jenkins controllers, agents, jobs, and pipelines.

This change gives teams more flexibility when selecting Java versions for build workloads, while helping us prepare the platform for future Jenkins and JDK upgrades with lower operational risk.

What is changing

Java version selection can now be controlled at multiple levels:

• Controller level
• Folder level
• Job or pipeline level

We are also decoupling the Java runtime used by Jenkins agents from the Java version used inside build steps, including:

• Pipeline sh commands
• Freestyle job shell steps
• Jobs that need a specific JDK version for compilation, testing, or tooling

This means Jenkins agents can run on the Java version required by the Jenkins platform, while individual jobs and pipelines can still use the Java version required by the application being built.

Why this matters

This update helps teams:

• Adopt newer Java versions in a controlled way
• Continue supporting workloads that require older Java versions
• Reduce risk during future Jenkins and JDK upgrades
• Avoid coupling Jenkins platform upgrades to every application build requirement
• Give individual teams more control over the Java version used by their jobs and pipelines

Impact

This is a non-disruptive change.

There is no expected downtime and no expected impact to running jobs or pipelines.

Existing configurations will continue to work as they do today unless a Java version is explicitly overridden.

For managed Jenkins agents, StackTrack will ensure the Jenkins agent runtime uses a supported Java version for the Jenkins platform. For Jenkins LTS 2.555.1 and later, Jenkins requires Java 21 or Java 25 on both the controller JVM and agent JVMs. (Jenkins)

Selecting a Java version in jobs and pipelines

Once this change is enabled, customers can select the Java version used by their jobs or pipelines by setting the JENV_VERSION environment variable.

Example:

pipeline {
  agent any

  environment {
    JENV_VERSION = '17'
  }

  stages {
    stage('Check Java version') {
      steps {
        sh 'java -version'
      }
    }
  }
}

Using Jenkins JDK tools

Customers can also use Jenkins JDK tools instead of setting JENV_VERSION directly.

Example declarative pipeline:

pipeline {
  agent any

  tools {
    jdk 'JDK21'
  }

  stages {
    stage('Check Java version') {
      steps {
        sh 'java -version'
      }
    }
  }
}

Example scripted pipeline:

node {
  def javaHome = tool 'JDK21'
  env.JAVA_HOME = javaHome
  env.PATH = "${javaHome}/bin:${env.PATH}"

  sh 'java -version'
}

Customers with permanent agents

Customers who own or manage their own permanent Jenkins agents must ensure those agents are upgraded to Java 21 or Java 25 before moving to Jenkins LTS 2.555.1 or later.

From Jenkins LTS 2.555.1, Java 21 or Java 25 is required for both the Jenkins controller and agent JVMs. Java 17 is not supported for Jenkins 2.555.1 and later. (Jenkins)

This does not prevent jobs from using older Java versions for build steps where required.

The Jenkins agent runtime and the Java version used inside a job or pipeline can now be managed separately.

Updated on: 29/04/2026