PATH+KEY environment variable precedence order in CloudBees CI

Last Reviewed:2026-07-15()
2 minute readKnowledge base

Overview

CloudBees CI supports the PATH+KEY environment variable syntax, which prepends a value to the existing PATH rather than replacing it. This mechanism is commonly used to inject tool directories — such as Maven, Gradle, Node.js, Python, Go, or any custom CLI — at different configuration scopes: Global Properties (Manage Jenkins  System), folder level (via the Folders Plus plugin), and node level.

When the same tool’s directory is added via PATH+KEY at multiple scopes, users often expect the most specific scope (node level) to take precedence. In practice, Global Properties always wins — regardless of what is configured at folder or node level. This causes jobs to silently resolve the wrong tool version, with no warning or error.

A common symptom: after updating a node’s PATH with a newer tool version — for example, following an AMI rollout or agent image update — jobs continue to execute using an older version defined in Global Properties.

Confirmed precedence order

When a job runs, CloudBees CI assembles the final PATH by prepending values in the following order:

  1. Global Properties (assembled first — occupies the front of PATH)

  2. Folder level (only applies to jobs inside that folder)

  3. Node level (assembled last among these three)

  4. OS default PATH

Because Global Properties is prepended first, its value occupies the first position in the resulting PATH. The shell resolves the first matching executable it finds, so a binary directory defined in Global Properties is always found before folder-level or node-level entries.

CloudBees CI does not warn when a higher-scope PATH+KEY entry shadows a lower-scope one. There is no conflict detection or log message indicating that a node-level or folder-level entry has been overridden.

Scope of impact

What this affects

Any executable that CloudBees CI resolves by searching $PATH at shell execution time, when that tool’s directory is added via PATH+KEY at multiple scopes. Examples: Maven (mvn), Gradle (gradle), Node.js/npm, Python/pip, Go, or any custom CLI tool directory injected via PATH+KEY.

What this does NOT affect

  • Tool Installations — Tools configured under Manage Jenkins  Tools and referenced via the tools {} block or tool step resolve to an explicit path chosen by Jenkins' tool resolver, bypassing PATH search entirely.

  • Plain (non-PATH+KEY) environment variables — A simple key-value variable such as MAVEN_HOME=/some/path follows normal environment variable override rules, which differs from PATH+KEY prepending.

Mitigation options

  • Use Tool Installations instead of PATH+KEY for tools that support it — bypasses this precedence behavior entirely and gives explicit, per-job version selection.

  • Remove the PATH+KEY entry from Global Properties if node-level or folder-level control is desired — eliminates the shadowing at its source.

  • Update the Global Properties entry if a single version should apply organization-wide — appropriate only when uniformity is the intended goal.

  • Use withEnv for a one-off per-job override — evaluated at runtime and prepends ahead of Global Properties, without changing shared controller configuration.

Tested product/plugin versions

  • CloudBees CI on modern cloud platforms - managed controller 2.555.3.36983, Kubernetes, RHEL 9.8, Java 21 (OpenJDK)

  • Folders Plus plugin (folder-level environment variables)

  • Maven 3.8.2 and Maven 3.9.9

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.