Jenkins Plugin Parent POM: What It Controls and Where It Binds

The Problem It Solves: One Build Recipe for Hundreds of Plugins

Jenkins hosts thousands of plugins, each with its own build quirks. Without a shared parent, every plugin would duplicate Maven configuration for the HPI plugin, the Stapler plugin, test harness versions, and release profiles. The plugin-pom centralizes that. It decouples plugin builds from the core Jenkins repository, both in Maven terms and in repository terms, so plugin developers do not need to track core's internal build files. The intended audience is anyone who writes or maintains a Jenkins plugin and wants a baseline build that matches what Jenkins infrastructure expects. If you are not building a Jenkins plugin, this project has nothing for you. It is a Maven parent POM, not a library or a tool you run directly.

How the Parent POM Works: Inheritance, Properties, and Profiles

The mechanism is standard Maven parent inheritance. You declare the parent in your plugin's pom.xml with groupId org.jenkins-ci.plugins, artifactId plugin, and a version. The parent then provides plugin configurations, dependency management, and profiles. The key is the set of overridable properties. The mandatory one is jenkins.version, which sets the Jenkins core version your plugin compiles against and tests with. Other properties control the Jenkins Test Harness version, the HPI Maven plugin version, and the Stapler Maven plugin version. The README explicitly warns not to set hpi-plugin.version lower than what the parent specifies. There are also marker files: creating .mvn_exec_node or .mvn_exec_yarn in your repo triggers npm or yarn integration, and the parent then expects corresponding node.version and npm.version properties. This is a convention-over-configuration design, but the conventions are strict.

Getting It Running: A Minimal Plugin POM and the First Build

To use it, edit your plugin's pom.xml. Replace your existing parent with the plugin parent, and set the version to a released version from the releases page. The README gives a minimal example: a parent block with relativePath set to empty, and a properties block with jenkins.version set to something like 2.361.4. Then run mvn install or mvn test as usual. The parent also lets you run the local Jenkins instance with mvn hpi:run, and by default the setup wizard is skipped. If you want the wizard, run mvn -Dhudson.Main.development=false hpi:run. For formatting, you opt in by setting spotless.check.skip to false and removing any existing Spotless config. Then mvn spotless:apply formats your code. That is the whole onboarding: change the parent, set jenkins.version, and build.

The Incrementals and Formatting Trade-offs

One notable feature is the Incrementals integration. You can configure your plugin to treat every commit as a release candidate, which is a shift from the usual release-per-feature model. That can speed up testing but also means your plugin's version numbers become less predictable. The formatting story is a trade-off. Spotless is not enabled by default; you must explicitly set spotless.check.skip to false. The README advises that after formatting an existing repo, you should squash merge the PR and create a .git-blame-ignore-revs file to hide the formatting commit. That is honest about the disruption: formatting an entire codebase creates a noisy commit, and the parent gives you a way to mitigate that, but it is still a one-time cost. The 'format as you build' profile, may-spotless-apply, is active only if you add it to your settings.xml, which is an extra step that many teams will skip.

Where the Parent POM Can Bite You: JUnit 4 Ban and Test Skipping

The ban-junit4-imports check is a good idea but has a narrow scope. It only checks imports in your source code. It does not catch uses of JUnit 4 classes from dependencies, nor fully qualified class names. So you can still accidentally use JUnit 4 through a transitive dependency, and the check will not flag it. That is a real limitation. Another trap is the release process. The README states that tests are skipped during the perform phase of a release by default. If you rely on tests running during release, you must set release.skipTests to false. That is a surprising default for a release process, and it is easy to miss. Also, the benchmark profile is selective: when you run mvn -P jmh-benchmark test, no tests other than JMH benchmarks run. And benchmark classes must start or end with the word Benchmark, otherwise they are ignored. That is a strict naming convention that can silently exclude your tests.

Version Requirements: The Hard Floor You Must Accept

Version 5.0 raises the baseline to Jenkins 2.479 or newer and JDK 17 or newer. That is a hard requirement, not a suggestion. If your plugin still targets older Jenkins versions, you cannot simply upgrade the parent; you would have to stay on an older parent version, which means you lose newer features and fixes. The README lists the history: since 4.52, Jenkins 2.361 and JDK 11; since 4.40, Java 17 support. This shows a clear upward drift. For plugin maintainers, this is the main decision point. Upgrading the parent forces a minimum core version on your users. If your plugin is used by enterprises on older Jenkins installations, that can be a deal-breaker. The README points you to the developer documentation for choosing a baseline, but the parent itself enforces the floor.

Alternatives: Rolling Your Own or Using a Different Parent

The obvious alternative is to not use this parent POM at all. You can write your own parent POM or configure each plugin independently. That gives you full control over versions and checks, but you lose the alignment with Jenkins infrastructure. For example, the Jenkins test harness and HPI plugin versions are managed here; if you manage them yourself, you must track releases and compatibility manually. Another alternative is to use a different Maven parent that provides similar build conventions, but no other parent has the same integration with Jenkins-specific plugins like hpi and stapler. You could also use a build tool other than Maven, like Gradle, but the Jenkins plugin ecosystem is heavily Maven-centric, so you would be fighting the current. The real difference is control versus consistency. This parent trades flexibility for a known-good configuration.

Maintenance and License: What You Are Committing To

The project is licensed under MIT, which is permissive and does not impose copyleft obligations on your plugin code. That is a low-risk license for commercial use. Maintenance cost is moderate. The parent POM is actively maintained, with releases roughly monthly as of mid-2026. Each release may change defaults or add checks. You do not need to upgrade every time, but staying on an old version means you miss security fixes or compatibility updates. When you do upgrade, you need to re-test your plugin's build, because the parent can change dependency versions or introduce new checks. The README warns about the hpi-plugin.version, so you should verify that your plugin does not override it to a lower version. There is also the .git-blame-ignore-revs file to maintain if you adopt Spotless. Overall, the maintenance burden is on the plugin developer to keep up with parent releases and to understand what each new version changes.

Editorial conclusion

Adopt this parent POM if you maintain a Jenkins plugin and want consistent builds, test harness alignment, and access to incrementals and Spotless integration. Do not adopt it if you need to support Jenkins versions below 2.479 or JDK below 17, since version 5.0 enforces those baselines. Before upgrading, verify your plugin's dependency tree against the new parent, especially the hpi-plugin.version and stapler-maven-plugin.version, and check that your existing Spotless or JUnit 4 configurations do not conflict with the parent's checks. Also confirm your release process can handle tests being skipped during the perform phase by default.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes