Upgrading to Jenkins LTS 2.319.x

Each section covers the upgrade from the previous LTS release, the section on 2.319.1 covers the upgrade from 2.303.3.

Upgrading to Jenkins 2.319.2

Triggering Builds in Scripted Clients Without a Security Realm

Jenkins used to allow triggering builds using HTTP GET requests when no security realm and authorization strategy are defined. This is newly prohibited since Jenkins 2.319.2 and 2.330 as this could be abused via CSRF even when Jenkins is operated on a private network.

HTTP POST requests to Jenkins need to provide a CSRF token (crumb) unless they authenticate using a user-specific API token. When Jenkins is configured without security realm, there is no way to authenticate using an API token, so any scripted clients triggering builds first need to obtain a CSRF crumb from the crumb issuer as described in the documentation.

Upgrading to Jenkins 2.319.1

Built-In Node Name and Label Migration

As part of the terminology cleanup effort, the built-in node was renamed from "master node" to "built-in node" in Jenkins 2.307 and in Jenkins 2.319.1. This is not just a change affecting the UI and documentation: The node name affects the implicitly assigned label of the node (and consequently the NODE_LABELS environment variable), as well as the NODE_NAME environment variable.

The NODE_NAME environment variable in Pipelines is set by the Pipeline: Nodes and Processes plugin. In plugin version 2.39 and earlier, this value is always master. Update to version 2.40 or newer to get consistent behavior between job types.

Affected Features

Jenkins features using node labels are therefore potentially impacted by any such changes. These features include:

  • Label assignments of various project types, both on the top level (e.g. Freestyle jobs) and within jobs (e.g. node statements in Scripted Pipeline, label parameters to agent sections in Declarative Pipeline, or Matrix Project axes).

  • Label assignments of features like custom tool auto-installers, typically used to distinguish OS platforms.

  • Any custom build scripts whose behavior is different based on the NODE_NAME or NODE_LABELS environment variables (or their env global variable equivalent in Pipeline).

  • Any similar features in plugins.

Migration

Due to the potential impact to build behavior, instances upgrading Jenkins to version 2.307 or newer do not automatically get these behavior changes applied. Instead, an administrative monitor informs administrators about this change and allows them to apply it.

Before applying the built-in node name and label migration, administrators are advised to review their configuration and build scripts to assess the impact to their instance and jobs.

Most problems with label assignments can likely be worked around by manually assigning the label master to the built-in node and then migrating affected configuration incrementally to not need this workaround.

Plugin Compatibility

Known Incompatible Plugins

Use this Jira query to find compatibility issues tracked in the Jenkins Jira.

Use this GitHub query to find compatibility issues tracked on GitHub.

Reporting Incompatible Plugins

Please report problems in the respective plugin’s issue tracker.

If the affected plugin uses the Jenkins Jira to track issues, please add the label built-in-node-migration-regression.

If the affected plugin tracks issues on GitHub, please make sure to mention the Jenkins pull request that implemented the change in your issue.

Woodstox implementation removed

The Woodstox implementation of the StAX API from Jenkins core has been removed from Jenkins core. Users of the Azure Artifact Manager, Azure Container Agents, Azure Storage, and Azure SDK API plugins must upgrade those plugins to the latest versions prior to this core upgrade.

Ant deprecated classes removed

Deprecated, unsafe classes that had been previously copied from Apache Ant to Jenkins core have been removed. The unmaintained Docker slaves plugin is incompatible with this change.