Dependency Management

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Plugins depend on specific versions of libraries and of other plugins, each of which is versioned independently. Each dependency may have dependencies of its own and different versions of different libraries and plugins may not be compatible with each other. Moreover, the dependencies can change with each Jenkins release, so managing these dependencies manually can be difficult and time consuming.

Jenkins has tools that simplify dependency management:

Jenkins core BOM

Jenkins core provides a Maven Bill Of Materials (BOM) that centrally defines versions of various libraries used by Jenkins. If you are using Maven to build your plugin, then you can simplify dependency management by importing this BOM, at jenkins.version. Dependency versions are then automatically synchronized with the version of Jenkins against which you are building.

Library dependency issues may cause Require upper bound dependencies build errors such as:

[WARNING] Rule 4: org.apache.maven.plugins.enforcer.RequireUpperBoundDeps failed with message:
Failed while enforcing RequireUpperBoundDeps. The error(s) are [
Require upper bound dependencies error for commons-codec:commons-codec:1.9 paths to dependency are:
+-org.jenkins-ci.plugins:blueocean-display-url:2.3.1-SNAPSHOT
  +-commons-codec:commons-codec:1.9
and
+-org.jenkins-ci.plugins:blueocean-display-url:2.3.1-SNAPSHOT
  +-org.jenkins-ci.main:jenkins-core:2.195
    +-commons-codec:commons-codec:1.12
,
Require upper bound dependencies error for org.slf4j:jcl-over-slf4j:1.7.25 paths to dependency are:
+-org.jenkins-ci.plugins:blueocean-display-url:2.3.1-SNAPSHOT
  +-org.slf4j:jcl-over-slf4j:1.7.25
and
+-org.jenkins-ci.plugins:blueocean-display-url:2.3.1-SNAPSHOT
  +-org.jenkins-ci.main:jenkins-core:2.195
    +-org.slf4j:jcl-over-slf4j:1.7.26

This error says that a conflict exists between the versions of commons-codec and jcl-over-slf4j specified by the plugin versus Jenkins core. See Understanding requireUpperBoundDeps failures and fixes for more information.

In many cases, upper bounds dependencies errors are best resolved by updating the Jenkins core Bill of Materials and by using the Jenkins plugin Bill of Materials.

Update the Jenkins Core Bill of Materials (BOM)

Update the parent pom version with the following commands:

mvn versions:update-parent
mvn clean verify

See the video below for a step by step guide to updating the parent pom.

Update the parent pom

Jenkins plugin BOM

The plugin bill of materials (BOM) defines the versions of various plugins used by specific Jenkins versions. The plugin bill of materials includes many commonly used plugins and simplifies dependency management for plugins that depend on other plugins.

A plugin that tests its Pipeline implementation typically depends on several Pipeline plugins. The plugin BOM provides Pipeline plugin version numbers so that the developer does not need to maintain the independent version numbers of the Pipeline plugins.

The plugin bill of materials is defined in the dependencyManagement section of your pom.xml file. To use the Jenkins plugin BOM in your plugin:

  1. Confirm that you are using the current parent pom with the command mvn versions:update-parent

  2. Locate the most recent plugin bom version number on the plugin bom releases page

  3. Copy the dependencyManagement section from the pom.xml file in that directory

  4. Insert this dependencyManagement section into the pom.xml file for your plugin

    <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.jenkins.tools.bom</groupId>
            <artifactId>bom-2.401.x</artifactId>
            <!-- Latest version goes here -->
            <version>2643.vfa_93ff299d20</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

  5. Remove the <version> values from plugin dependencies in your plugin’s pom.xml

  6. Rebuild your plugin to see if this solves your dependency issues. Many commonly used plugins are included in the plugin pom. However, not all plugins are included. You may need to iterate on removing <version> values from specific plugins

See the plugin BOM documentation for further details. The video below demonstrates how to add the plugin BOM to a Jenkins plugin.

Simplify plugin dependency management with the plugin BOM

Dependabot

GitHub Dependabot can automate plugin dependency management. Newly created plugins built from the Jenkins plugin archetype include Dependabot by default.

Existing plugins need to configure Dependabot in their existing plugin repository. See the video below for an example that adds Dependabot to an existing plugin repository:

Automate dependency management with Dependabot
References