Choosing a Jenkins version to build against

Your plugin’s POM controls which version of Jenkins it is building/testing against.

Choosing a version

You need to balance compatibility and features:

  • Keeping the Jenkins version your plugin builds against low will allow more users to install and use your plugin. In particular, the LTS Release Line is based on slightly older releases to provide a more stable experience for conservative users.

  • Building against recent Jenkins versions allows you to use recently added core features and API from your plugin. You will also use that newer version for mvn hpi:run, so it may be easier to test your plugin with newer Jenkins releases.

  • Do not use versions no longer supported by the update center, which is currently anything older than 2.304 for weekly releases, and 2.289.3 for LTS releases. Note that the lowest supported version changes about every week (weekly release) or every month (LTS release), so these specific versions will be a bad choice soon.

  • Prefer an LTS version over weekly versions.

    • If you are based on the currently active LTS line, try to stay on the first release in that line (2.xxx.1) unless you have a specific reason to depend on a subsequent micro release (such as a need to test against a recently released security fix).

    • If you are based on a historical LTS line (at least one release in a newer line has been published), prefer to depend on the last release in that line (typically 2.xxx.3).

  • Prefer releases that result in few or no implied plugin dependencies. Sometimes Jenkins core features are moved into plugins, and any plugin with a dependency on an older core release will have an implied dependency on the new plugin. This makes plugin management more difficult for administrators, so core dependencies should ideally be chosen so that there are no, or few, implied dependencies. See split-plugins.txt for details. At this time, a dependency on Jenkins versions newer than 2.356 will not result in such implied dependencies.

There are statistics of core versions by plugin that can help you decide. These are updated monthly. When updating the core dependency, choose the newest LTS version that doesn’t exclude a majority of your existing users (by requiring a newer Jenkins than they have).

If you are packaging a pure API library (one that does not depend on Jenkins APIs) then you should ignore newer Jenkins versions and pick an older LTS. Something around 1 year old that does not have too many detached plugins makes a good choice and 2.289.3 would be a reasonable candidate.

At the moment, the Jenkins releases 2.332.4 and 2.346.3 make good core dependencies. You could also consider 2.361.1 if there are specific reasons, like new features, to want something newer; 2.289.3 and 2.303.3 and 2.319.3 would be reasonable conservative choices.

Changing the minimum required version

Set the jenkins.version property in pom.xml to the version you need to depend on.

<properties>
  <jenkins.version>2.346.3</jenkins.version>
</properties>