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. 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.

  • 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.