Plugin Utilities API

ID: plugin-util-api

Jenkins Plugin Jenkins Version Jenkins Version Jenkins GitHub Actions

This Jenkins plug-in provides utility classes that can be used to accelerate plugin development.

How to use the plugin

In order to use this small library, add a maven dependency to your pom:

  <version>[latest version]</version>

General structure of a reporter

In this section I will explain some fundamentals of the design of Jenkins, i.e. the Java model and the associated user interface elements. If you are already familiar on how to implement the corresponding extension points of a reporter plugin (see section Extensibility in Jenkins' developer guide), then you can skip this section and head directly to Extending Jenkins object model.

Jenkins organizes projects using the static object model structure shown in Jenkins design - high level view of the Java model.

Jenkins design
Figure 1. Jenkins design - high level view of the Java model

The top level items in Jenkins user interface are jobs (at least the top level items we are interested in). Jenkins contains several jobs of different types (Freestyle jobs, Maven Jobs, Pipelines, etc.).

Each of these jobs contains an arbitrary number of builds (or more technically, runs). Each build is identified by its unique build number. Jenkins plugins can attach results to these builds, e.g. build artifacts, test results, analysis reports, etc. In order to attach such a result, a plugin technically needs to implement and create an action that stores these results.

These Java objects are visualized in several different views, which are described in more detail in the following sections. The top-level view that shows all available Jobs is shown in Jenkins view showing all available jobs.

Figure 2. Jenkins view showing all available jobs

Plugins can also contribute UI elements in these views, but this is out of scope of this guide.

Each job has a detail view, where plugins can extend corresponding extension points and provide summary boxes and trend charts. Typically, summary boxes for reporters are not required on the job level, so I describe only trend charts in more detail, see ECharts Jenkins plugin.

Job details
Figure 3. Jenkins view showing details about a job

Each build has a detail view as well. Here plugins can provide summary boxes similar to the boxes for the job details view. Typically, plugins show here only a short summary and provide a link to detailed results, see Jenkins view showing details about a build for an example.

Build details
Figure 4. Jenkins view showing details about a build

The last element in the view hierarchy actually is a dedicated view that shows the results of a specific plugin. E.g., there are views to show the test results, the analysis results, and so on. It is totally up to a given plugin what elements should be shown there. In the next few sections I will introduce some new UI components that can be used to show the corresponding results in a pleasant way.

Extending Jenkins object model

Since reporters typically are composed in a similar way, I extended Jenkins' original object model (see Jenkins design - high level view of the Java model) with some additional elements, so it will be much simpler to create or implement a new reporter plugin. This new model is shown in Jenkins reporter design - high level view of the model for reporter plugins. The central element is a build action that will store the results of a plugin reporter. This action will be attached to each build and will hold (and persist) the results for a reporter. The detail data of each action will be automatically stored in an additional file, so the memory footprint of Jenkins can be kept small if the details are never requested by users. Additionally, this action is also used to simplify the creation of project actions and trend charts, see [trend-charts].

Jenkins reporter design
Figure 5. Jenkins reporter design - high level view of the model for reporter plugins

You can find several examples of Jenkins plugins that use this library, e.g. the Warnings Next Generation plugin or the Forensics plugin.

ArchivesGet past versions
Version: 2.1.0
Requires Jenkins 2.249.1
Installs: 173,250
Ulli Hafner
Help us improve this page!
To propose a change submit a pull request to the plugin page on GitHub.