Bill of Materials for Jenkins plugins
This repository implements a Maven BOM which can be used in a plugin POM to more easily manage dependencies on other common plugins. This is important because version management is a common annoyance. See JENKINS-47498 for the background.
If you are interested in a Bill of Materials for Jenkins core components, see this page.
After selecting your plugin’s LTS baseline:
just import the latest BOM from that line:
<dependencyManagement> <dependencies> <dependency> <groupId>io.jenkins.tools.bom</groupId> <artifactId>bom-2.289.x</artifactId> <version>…</version> <scope>import</scope> <type>pom</type> </dependency> </dependencies> </dependencyManagement>
Now you can declare dependencies on many plugins without needing to specify a version:
<dependency> <groupId>org.jenkins-ci.plugins.workflow</groupId> <artifactId>workflow-cps</artifactId> <scope>test</scope> </dependency>
You can always override a version managed by the BOM if you wish, but if you find the need to use a newer version, first try just updating the version in the BOM and cutting a new release of it.
When starting to use the BOM in an existing plugin,
you may find that many existing dependencies do not need to be expressed at all and can be deleted,
if they were added solely to satisfy the
RequireUpperBoundDeps Enforcer rule or similar.
Maven will automatically add transitive dependencies to your classpath,
so you should only need to declare an explicit dependency on another plugin when:
- You compile against it. (Use
testscope if it is only used in tests.)
- It is required to be present and not otherwise loaded transitively.
workflow-durable-task-stepare commonly required for tests which run Pipeline builds.)
can offer clues about unused plugin dependencies, though you must evaluate each carefully since it only understands Java binary dependencies (what is required for compilation, more or less).
For people potentially working on the BOM itself, not just consuming it.
Updating a plugin
You can try just incrementing plugin versions in
If CI passes, great!
Dependabot will try doing this as well.
In cases where two or more plugins must be updated as a unit (JENKINS-49651), file a PR changing the versions of both.
Adding a new plugin
Insert a new
dependency in sorted order to
Make sure it is used (perhaps transitively) in
Ideally also update the sample plugin’s tests to actually exercise it,
as a sanity check.
Avoid adding transitive dependencies to
sample-plugin/pom.xml. It is supposed
to look as much as possible like a real plugin, and a real plugin should only
declare its direct dependencies and not its transitive dependencies.
You can also add a
for a plugin which specifies
You should introduce a POM property so that the version is not repeated.
The build will enforce that all transitive plugin dependencies are also managed.
If the build fails due to an unmanaged transitive plugin dependency, add it to
The CI build tries running the Plugin Compatibility Tester (PCT)
on the particular combination of plugins being managed by the BOM.
This catches mutual incompatibilities between plugins
(as revealed by their
and the specified Jenkins LTS version.
If there is a PCT failure, fix it in the plugin with the failing test, and when that fix is released, try updating the BOM again.
To reproduce a PCT failure locally, use something like
PLUGINS=structs,mailer TEST=InjectedTest bash local-test.sh
optionally also passing
to reproduce image-specific failures.
Note that to minimize build time, tests are run only on Linux, against JDK 8, and without Docker support. It is unusual but possible for cross-component incompatibilities to only be visible in more specialized environments (such as Windows).
A separate BOM artifact is available for the latest weekly, current LTS line and a few historical lines.
BOMs should only specify plugin version overrides compared to the next-newer BOM.
sample-plugin will use the weekly line by default,
and get a new POM profile for the others.
To get ahead of problems, prepare the draft PR for a line as soon as its baseline is announced.
The CI build (or just
mvn test -P2.nnn.x) will fail if some managed plugins are too new for the LTS line.
is a handy way to find the most recently released plugin version compatible with a given line,
according to the
The UC currently maintains releases for the past 400 days
so it is reasonable to retire BOMs for lines older than that.
Automatic given JEP-229 when PRs matching certain label patterns are merged.
For the common case that only lots of
dependencies PRs have been merged,
can be triggered manually from the Actions tab after a
master build has succeeded.
This repository is integrated with “Incrementals” JEP-305:
- Individual BOM builds, including from pull requests, are deployed and may be imported on an experimental basis by plugins.
(The plugin’s POM must use the
gitHubRepoproperty as shown in workflow-step-api-plugin #58.)
- Pull requests to the BOM may specify incremental versions of plugins, including unmerged PRs. (These should be resolved to formal release versions before the PR is merged.)
Together these behaviors should make it easier to verify compatibility of code changes still under review.
This repository uses Dependabot to be notified automatically of available updates, mainly to plugins. (It is not currently possible for Jenkins core updates to be tracked this way.)
Release Drafter is also used to prepare changelogs for the releases page.