Introduction
IntroductionPre-installation requirementsInstallUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirements for KubernetesKubernetes Gateway API for CloudBees CI on modern cloud platformsKubernetes Gateway API supported implementationsGateway API features required by CloudBees CIVerify Kubernetes Gateway API prerequisitesDeploy a Kubernetes Gateway API namespace topologyInstall CloudBees CI with Kubernetes Gateway APIMigrate from Ingress to Gateway APIClean up Helm values for Gateway API migrationVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionPre-installation requirementsInstallVerify and inspect Docker imagesUninstall
IntroductionSystem requirementsVerify Docker imagesInstall operations centerInstall client controllersVerify build componentsVerify WAR files
IntroductionHA fundamentalsGet ready for HAInstall HA on modern cloud platformsInstall HA on traditional platformsHA considerationsHigh Availability (active/passive) installation for CloudBees CI on traditional platforms
Introduction
IntroductionCommon Pipeline termsPipeline project typesCloudBees proprietary features for Pipelines
IntroductionPipeline development utilitiesDetermine plugin compatibilityPipeline best practices
IntroductionUse Declarative Pipeline syntaxUse Scripted Pipeline syntax
IntroductionPipeline prerequisitesCreate your first PipelineSelect an agent for your Pipeline jobCreate a Pipeline from SCMCreate a Pipeline in the UIUnderstand and implement Pipeline as Code
IntroductionConfigure advanced Scripted PipelineConfigure the build stageConfigure the deploy stageConfigure optional step argumentsConfigure the test stageCreate a JenkinsfileCustomize parametersHandle failuresString interpolationUse multiple agentsWork with the environmentReuse configuration files
IntroductionEnable artifact traceability with fingerprintingTrigger jobs with a simple webhookRestore filesVisualize the PipelineInsert checkpointsSecure PipelinesConfigure Pipelines with user-scoped credentialsEnforce standards with Pipeline PoliciesSpecify a matrix of one or more dimensionsConvert a Freestyle project to a Declarative PipelinePipeline builds and High Availability (active/active)
IntroductionRestart aborted buildsSkip next buildConsolidated Build View pluginCloudBees Quiet Start pluginCloudBees Template pluginCloudBees Workspace Caching
IntroductionTrigger a job with a notification event using Cross Team CollaborationEnable external notification events with external HTTP endpointsCluster-wide copy artifactsCluster-wide job triggers
IntroductionSet up a Pipeline Template CatalogDefine Pipeline Template CatalogsSet up a Pipeline TemplateParameter types in the template.yaml fileManage Multibranch Pipeline options in the template.yaml fileManage Pipeline Template Catalogs in bulkExample full Maven/Java app Jenkinsfile
IntroductionBranch SourceBitbucketGitHubGitBranch Property StrategyExamples
CloudBees Docker Traceability
Introduction
Introduction
Introduction
IntroductionGet startedNavigate the operations center interfaceProvision agents in a separate Kubernetes cluster from a managed controllerProvision a controller in a different OpenShift project than the operations centerManage controllersManage controllers in specific Kubernetes namespacesMigrate an existing managed controller to High Availability (HA)Manage agentsOpt in to the Git LFS agent imageManage SSH credentialsShared agentsShared configurationsShared cloud configurationTrigger restrictionsChange NFS storage locationQuiet startMove/Copy/PromoteCluster operationsInbound agentsUse Kaniko with CloudBees CIUse Buildkit with CloudBees CIUsing self-signed certificates in CloudBees CI on KubernetesSidecar injector for self-signed certificates on OpenShiftAuto-scale nodes on EKSEnable auto-scaling nodes on GKECloud Foundry CLI PluginCloudBees CI ServiceNow integrationCreate projects based on a GitHub repository structureUse GitHub App authenticationCreate Multibranch Projects and Organization Folders with large repositoriesController Lifecycle Notifications plugin
IntroductionGet startedNavigate the operations center interfaceManage client controllersMigrate from High Availability (active/passive) to High Availability (active/active) on CloudBees CI on traditional platformsManaging agentsManage SSH credentialsShared agentsShared configurationsShared cloud configurationTrigger restrictionsQuiet startMove/Copy/PromoteCluster operationsInbound agentsCloudBees CI ServiceNow integrationCreate projects based on a GitHub repository structureUse GitHub App authenticationCreate Multibranch Projects and Organization Folders with large repositories
Introduction
Trust modelCentrally manage securityPod Security Admission
Use single sign-on (SSO) in the operations centerConfigure SAMLIntegrate Microsoft Entra IDSet up SSO Relay for CloudBees CI single sign-on
Role-based access control (RBAC)Example RBAC configurationsRBAC auto-configurer pluginRestrict job triggersAccess controls on the operations centerAccess controls on controllersOperations center specific permissionsAuthentication mappingDelegate administrationFoldersFolders Plus
Authenticate automated processes with CloudBees CI service accountsService account scope and visibilityGet started with CloudBees CI service accountsService accounts CLIService account API endpointsCreate and use service accounts with Configuration as CodeService account security considerations
OAuth client credential bindingRestricted credentialsInjecting secretsMask ephemeral secrets in Pipeline build logsEnhanced credentials maskingExternal secrets managementCyberArk credential providerManage secrets with HashiCorp VaultShared credentials administrative monitor
Cross-controller triggersTest the SSH connection to an agentManage build agents with Nodes PlusExtended security settings
Beekeeper security warningsCloudBees administrative monitorsSecurity recommendationsData collection
Replace an expired certificateList of URLs that need accessBlock access to URL patternsServe resources from JenkinsVerify Helm charts with a signature
Introduction
Introduction$JENKINS_HOME directoryBest practices for backup and restoreBack up $JENKINS_HOME manuallyBackup a Role-Based Access Control configurationRestore backup files manuallyRestore credentialsConfigure backups using the CloudBees Backup pluginSchedule backups in the CloudBees Backup pluginRestore backups created with the CloudBees Backup pluginBackup and restore on KubernetesBackup and restore on AWSBackup and restore Kubernetes cluster resources using VeleroRun backups using cluster operations
IntroductionConfigure multiple client controllers with the Jenkins CLI toolConfigure an alias for the Jenkins CLI toolConfigure Jenkins CLI tool with non-TrustStore TLS certificates
CloudBees Inactive Items Plugin
Jenkins Health Advisor by CloudBees
Count and monitor user licenses with the CloudBees User Activity Monitoring plugin
Count and monitor user licenses with the CloudBees User License Counting (ULC) system
Introduction
IntroductionCasC requirementsCasC permissionsRecommended workflow
IntroductionExport a CasC configurationTransform an exported bundleAdvanced CasC bundle configurationValidate a CasC bundle
IntroductionGet started with Configuration as Code for the operations centerConfigure the operations center on modern platforms using CasCConfigure the operations center on traditional platforms using CasCRetrieve bundles using an SCMTroubleshoot CasC
IntroductionGet started with Configuration as Code for controllersDistribute CasC bundles to controllers from your operations centerAdd controller CasC bundles to the operations centerConfigure bundle availability for controllersSet up a client controller using CasCSet up a managed controller using CasCSet up a managed controller using the CasC Controller Bundle ServiceAdvanced topicsTroubleshoot CasC for controllers
IntroductionUpdate a CasC bundleBundle update timingReview the CasC update log
IntroductionPlugin management with CasCDetermine plugin compatibility using CasCCreate an alternate plugin download site
Create items using CasC
Configure RBAC with CasC
CasC CLI commands
CasC HTTP API
Introductionbundle.yaml file referencejenkins.yaml file referenceplugins.yaml file referenceplugin-catalog.yaml file referenceitems.yaml file referencerbac.yaml file referencevariables.yaml file reference
HA on EKS Performance Test
Support policies

Migrate to Java 25

5 minute read

Java 25 was released on September 16, 2025, as a long-term support (LTS) version. The Jenkins community supports running Jenkins with Java 25 since version 2.541.1 and CloudBees CI supports running in Java 25 since version 2.580.2.38434.

Java 25 is the default JDK in CloudBees CI container images starting with version 2.580.2.38434.

If you upgrade to CloudBees CI 2.580.2.38434 or later using the default container images, your operations center, controllers, and agents will run on Java 25 automatically, even if you do not change your image tags. If you are not ready to migrate, you can explicitly opt in to the Java 21 fallback images by using the -jdk21 image suffix. For more information, refer to JVM version on container images.

CloudBees has validated the core functionality and all plugins in the CloudBees Assurance Program (CAP) work correctly when using Java 25. Plugins that are not part of the CAP may work, but they have not been verified and may cause issues especially in mixed JVM scenarios.

If you manage your CloudBees CI on modern cloud platforms using Helm charts, both the operations center and controllers are automatically upgraded to Java 25, the same applies to agent images. If you are not using the CloudBees CI agent image, you need to manually update your agent image to include and use Java 25 as the default Java installation. Similarly, shared agents and cloud agents must be manually updated to use Java 25.

Supported configurations

CloudBees performs full test flows with the following supported JDKs or JREs:

  • OpenJDK JDK/JRE 21 - 64 bits

  • OpenJDK JDK/JRE 25 - 64 bits

CloudBees CI version 2.580.2.38434 or later

Table 1. CloudBees CI 2.580.2.38434 or later
Component Supported Java version

Operations center

Java 25 and Java 21

Controller and agents

Java 25 and Java 21

Operations center shared agents

Java 25 and Java 21

Action required

CloudBees supports mixed-mode JVM usage in CloudBees CI version 2.580.2.38434 or later, so you can transition to Java 25 without impacting CloudBees CI operations. CloudBees recommends that you migrate to Java 25 as soon as your environment is validated.

To migrate to Java 25, complete the following steps:

  1. Upgrade the JVM used to run CloudBees CI.

  2. Upgrade the CloudBees CI software.

Upgrade the JVM used to run CloudBees CI

Upgrade the JVM on all components to Java 25. Because CloudBees CI supports mixed-mode JVM usage, you can perform this upgrade without downtime, and the upgrade order is flexible.

  • Upgrade all agents (permanent and cloud agents) to Java 25. If you use custom build agents, update those podTemplates to Java 25.

    Upgrading to Java 25 only affects the runtime processes. Build jobs can continue to use different JDK versions (for example, 8, 11, 17, 21, or later) via container (for example, Docker) or VM definitions, tool locations, or environment variables in the build configuration (for example, a Jenkinsfile).

  • Upgrade all controllers to Java 25. If you use Helm charts, controllers are automatically upgraded to Java 25. If you have customized your deployment images, update them to use the -jdk25 image tag, or pin to the -jdk21 image tag to remain on Java 21 while you prepare to migrate.

  • Upgrade the operations center to Java 25. If you use Helm charts, the operations center is automatically upgraded to Java 25. If you have customized your deployment images, update them to use the -jdk25 image tag, or pin to the -jdk21 image tag to remain on Java 21 while you prepare to migrate.

All components must be running Java 25 before proceeding to Upgrade the CloudBees CI software.

Upgrade the CloudBees CI software

After verifying all components are healthy and running Java 25, upgrade the CloudBees CI software to 2.580.2.38434 or later.

  • As with any upgrade, CloudBees recommends that you back up $JENKINS_HOME and test the upgrade with a backup before you perform the upgrade on your production instance.

  • Controllers may remain on older software versions in accordance with the CloudBees maintenance lifecycle policies and can be upgraded at a later time.

  1. Upgrade CloudBees CI.

  2. Upgrade the plugins to support Java 25 and ensure compatibility with the most recent CloudBees CI releases.

    CloudBees has verified that all plugins in the CAP run without issue when using Java 25. If you discover a previously unreported issue, contact CloudBees Support. If the issue involves a Jenkins community plugin, CloudBees will report it and can suggest workarounds to avoid a broken plugin.

  3. Back up $JENKINS_HOME again after upgrading CloudBees CI and any required plugins.

Monitor the Java versions automatically

CloudBees CI on modern cloud platforms controllers and build agents verify Java requirements and notify users when they are launched using an unsupported version. The Versions Node Monitors plugin also provides detailed Java version monitoring.

JVM version on container images

Starting with CloudBees CI version 2.580.2.38434, Java 25 is the default JDK in all CloudBees CI container images. CloudBees also publishes fallback container images that include Java 21 for customers who are not yet ready to migrate.

CloudBees provides the following naming structure for container images:

  • an image without a suffix uses Java 25 (the default), and is equivalent to using the -jdk25 suffix

  • an image with the -jdk25 suffix indicates Java 25

  • an image with the -jdk21 suffix indicates the Java 21 fallback image

If you upgrade your CloudBees CI version without explicitly pinning to a -jdk21 image tag, the upgrade will automatically move your component to Java 25. If you need to stay on Java 21 (for example, while you validate plugin compatibility), you must explicitly set the image tag to use the -jdk21 suffix.

The Java 21 fallback images are intended to provide a short-term migration window and may be removed in a future release, in accordance with the CloudBees CI Java support policy. CloudBees recommends that you migrate to Java 25 as soon as your environment is validated.

Known issues

Refer to the following sections for any known issues that may affect your migration to Java 25.

JVM version on agents

All agents must run Java 25. You can validate each agent’s version using the Version Node Monitors plugin. This plugin provides information about the JVM version of each agent on the node management screen of your CloudBees CI instance. You can also configure this plugin to automatically disconnect any agent with an incorrect JVM version.

JVM version on operations center shared agents

JVM instances are used to establish the remoting connection between shared agents and controllers, as well as shared agents and the operations center. Additional JVMs could be installed on the agent computer and used as build tools by controller jobs. Those JVMs are irrelevant in this context, and there is no need to update them as part of the CloudBees CI Java 25 migration.

Depending on the launch method and agent configuration, you may have to take additional actions when you upgrade to Java 25.

"Launch agent by connecting it to the controller" launch method

This launch method is also known as an "inbound" agent. It is the agent that initiates the connection to the controller. This configuration also requires the agent computer to initiate the connection to the operations center. This launch method requires two JVM instances. One maintains the connection to the operations center and it is called the shared agent control JVM. The other connects to the controller when the agent is leased, and it is called the agent JVM. Both JVM instances must run Java 25.

"Launch build agents via SSH" launch method

This launch method is also known as an "outbound" agent. It means the controller is initiating the connection to the agent computer via SSH and then automatically starting the agent JVM.

There is no shared agent control JVM involved in this configuration. There is only one JVM, the agent JVM, which must run Java 25. The path to this JVM binary is configurable in the shared agent configurations.

Execute jobs on CloudBees CI

CloudBees CI jobs can be executed on Java versions that differ from the controller/agent runtime Java version. Generally, CloudBees CI allows any version of JRE/JDK to be invoked during the build. That includes executing Java commands from the CLI, as well as installing and executing build steps using a JDK managed by JDK tool installers.

Migrate to Java 21
Migrate historical User Activity Monitoring Plugin data