Jenkins : Java 11 Developer Guidelines

This page is a collaborative entry point for developer resources about developing and testing Jenkins to run on Java 11.

This page is not designed to receive status updates for user-facing issues. But you are more than welcome to check and report such issues so that they show on the dedicated Known Java 11 Compatibility issues wiki page. 

How to

Run Jenkins using Java 11

See the Java 11 Preview Availability announcement

Develop and test your plugin for running on Java 11

As a part of JEP-211, we request all plugins to remain compatible with Java 8 for now. But you may still need to run the tests with Java 11 so that you can verify the plugin's behavior. It is possible to pass "jvm" and extra Java properties to Maven Surefire plugin to just run tests, but it is easier to actually build & test plugins with JDK 11. Jenkins development tools have been updated to support that:

  1. For non-experimental releases you should always build the plugins with java.level=8 
  2. Use plugin-pom:3.29+ (changelog). Versions before 3.29 contain some updates to be able to build and test your plugins using JDK 11
  3. Plugins will be able to compile successfully with JDK 11 if and only if Jenkins Core version (jenkins.version) is above 2.138+
  4. You can update Jenkinsfile to run tests with Java 11. To workaround the Jenkins core requirement, a full configuration matrix may be used in buildPlugin():
    1. Example: Jenkinsfile in the Label Verifier Plugin

Some potential pitfalls to remember about:

  • The existing "mvn hpi:run" command will not work correctly on Java 11 unless Java modules are downloaded and passed to the environment ( JENKINS-54807 - Maven HPI Plugin or Plugin POM should automatically set up Java 11 environment for hpi:run Resolved )
  • If you use Mockito/PowerMock in your plugin tests, you may need to update to the recent versions with Java 11 support 
  • In some cases FindBugs may crash in some cases ( JENKINS-53692 - Plugin POM: FindBugs sometimes fails on Java 11 Resolved ), workarounds may be needed

See the "Known developer tools issues" for more known issues in Plugin POM and Jenkins plugins.

Make sure your plugin is tested in Continuous Integration on Java 8 and Java 11 at the same time

Since this addition, it is now recommended that you use the following configuration in your plugin: 

buildPlugin(configurations: buildPlugin.recommendedConfigurations())

By default, this will build your plugin:

  • on the default configuration, extracted from your pom.xml
  • on Jenkins 2.164.1 using a JDK 8
  • on Jenkins 2.164.1 using a JDK 11

All this both on Windows and Linux.

Release an experimental plugin version specifically for Java 11

Although we request all plugins to remain compatible with Java 8, in some cases it may be reasonable to release an experimental version for Java 11 early adopters.

In order to do that, we provide an Experimental Update Center for Java 11. Since Jenkins 2.155, if you run using Jenkins versions with Java 11 preview, Jenkins and Jenkins Docker plugins.txt installer (e.g. "workflow-support:experimental") will default to this experimental update center. It allows Java 11 early adopters to get patches without requiring deploying snapshots manually:

In order to do an experimental release for Java 11, all the following steps must be performed:

  • Develop the Java 11 code in a feature branch (e.g. "java11-support") so that it does not impact main release line
  • Add an "alpha" or "beta" marker to the version of your experimental plugin
  • Update to plugin-pom:3.29+ so your plugin embeds the new minimum version of Java requirement in its manifest
  • Set the plugin.minimumJavaVersion property in your pom.xml to 11 (see https://github.com/jenkinsci/plugin-pom/blob/master/CHANGELOG.md#329)

If if you forget about any of the bullets above, the update may impact Java 8 users. The long-term solution is already on its way, but is not delivered yet. Follow  JENKINS-55048 - Jenkins core should check plugin Minimum Java requirements in Update Center metadata Resolved  if you are interested.

Run Plugin Compat Tester (aka PCT) using Java 11

Documented in the PCT repository: https://github.com/jenkinsci/plugin-compat-tester#running-pct-with-custom-java-versions

Current status of many plugins (please comment there to get access, or send an email if you tested another opensource plugin).

Run Acceptance Test Harness (aka ATH) using Java 11

Documented on the ATH repository: https://github.com/jenkinsci/acceptance-test-harness/blob/master/docs/JAVA11.md

Jenkins Core known issues with Java 11

If you hit this issue  JENKINS-55150 - [jenkins-dev] jenkins-dev:run no longer has hot reload after 2.152 Resolved  about live reloading of resources in Jenkins, the current workaround is "mvn org.jenkins-ci.tools:maven-jenkins-dev-plugin:9.4.5.v20170502-jenkins-1:run"

Known developer tools issues

Please add known issues here. The preferred way is to create or find the associated JIRA in the Jenkins Issue Tracker, and add the "java11-devtools-compatibility". Then the issue  it will automatically show up in the list below.

If you cannot create a JIRA issue, please still feel free to add notes about your findings below.

(associated JIRA board for the following filter)

T Key Component(s) Summary P Status released as
Bug JENKINS-61105 core 2.204.3 rc fails to open folder in Java 8, throws class not found exception Blocker Closed Jenkins 2.227
Improvement JENKINS-57341 archetypes Plugin archetype and tutorial do Java 7 and Java 8 but not Java 11 Minor Closed
Bug JENKINS-57320 plugin-compat-tester Fix a possible regression introduced on JENKINS-56312 Blocker Resolved PCT 0.1.0
Bug JENKINS-56657 jenkinsfile-runner Can not build jenkinsfile-runner with JDK 11 Minor Open
Bug JENKINS-56492 acceptance-test-harness [ATH] Fix Javadoc failures on Java11 Major Resolved
Improvement JENKINS-55885 plugin-pom Update Maven HPI Plugin version to run on Java11 Minor Resolved Maven HPI Plugin 3.3, Plugin POM 3.37
Bug JENKINS-55692 platformlabeler-plugin Java 11 Javadoc generation fails in maven Minor Closed
Bug JENKINS-55541 git-plugin PCT on git plugin with JDK11 fails because of old powermock versions and xstream library dependencies Major Closed
New Feature JENKINS-55296 plugin-compat-tester Add support of running PCT main executable with Java 11 Minor Resolved
Bug JENKINS-55290 mailer-plugin, plugin-pom Missing META-INF/exposed.stapler-beans when building Mailer plugin with Java 11 Minor Fixed but Unreleased
Bug JENKINS-55205 saml-plugin Review findbugs error with some OS+JDK Minor Resolved saml-1.1.2
New Feature JENKINS-55200 gradle-jpi-plugin Gradle JPI plugin should be updated to support testing with Java 11 Minor Resolved
Bug JENKINS-55199 plugin-compat-tester PCT fails when cycle dependency on test scope Minor Closed https://github.com/jenkinsci/plugin-compat-tester/commit/7d7fa307cbd75e76bb084bac09012bc826a7722f
Improvement JENKINS-55162 core, plugin-pom Maven JAR Plugin should be updated to 3.1.1 in Plugin POM and Jenkins POM Minor Resolved Jenkins POM 1.51, Plugin POM 3.30
Bug JENKINS-55150 core [jenkins-dev] jenkins-dev:run no longer has hot reload after 2.152 Major Resolved
Bug JENKINS-55146 plugin-compat-tester, plugin-pom PCT sometimes crashes on Java 11 due to module read errors when using the docker image Major Fixed but Unreleased
Improvement JENKINS-55098 plugin-pom Build Flow: PowerMock and Mockito need massive updates for Java 11 Minor Resolved Plugin POM 3.32
Bug JENKINS-55097 plugin-compat-tester PCT cannot efficiently run Java 8/11 tests in Docker due to SUREFIRE-1588 Major Resolved
New Feature JENKINS-54906 custom-war-packager Custom WAR Packager should support producing Java 11-compatible JFR images Minor Resolved
New Feature JENKINS-54862 plugin-compat-tester PCT: Add support of passing plugin version overrides Minor Resolved
Authenticate to retrieve your issues
Showing 20 out of 39 issues