Jenkins - Plugin (*.hpi File)

> Jenkins

1 - About

Jenkins defines extension point, which are interfaces or abstract classes that model an aspect of a build system. See Extensions Points

Those interfaces define contracts of what need to be implemented, and Jenkins allows plugins to contribute those implementations.

Action is the primary ways plugins use to add components.

See:

You will find a lot of standard plugin on https://github.com/jenkinsci

Advertising

3 - File Structure

A plugin is really just a jar file that follows a certain set of conventions. Structure

A basic plugin structure is

File / Directory Description
pom.xml Maven pom file to build the plugin
src/main/java Java source files of the plugin
src/main/resources Jelly/Groovy views of the plugin
src/main/webapp Static resources of the plugin, such as images and HTML files.

4 - Steps

4.1 - Extension Point

A plugin simply is one of several class that implement (ie subclass) extension point, registering them with the Extension annotation for automatic detection by Jenkins.

Important Extension point example are:

  • or an action to add action link with icon and url on the Jenkins GUI in order to start a function or points to a report for instance
Advertising

4.1.1 - BuildStep Example

An plugin is generally a Buildstep such

All the build steps have a perform method that has the following parameters:

  • the build: the runtime build data such as:
    • rootdir: a unique directory where build related document can be stored
    • workspace: access to the workspace (where the svn data are stored)
  • launcher - a way to start processes
  • listener - a place to send output

4.1.2 - Metadata

The data over the implemented extesion point are generally hold in an inner class extending descriptor that hold Metadatas for the extension point (Example: BuildStepDescriptor<> for a BuildStep). The @Extension annotation must be placed on the inner descriptor class to let Jenkins know about this extension

4.2 - Configuration parameters

4.2.1 - Config.jelly

If configuration parameters for each individual instance are required, they're handled via a config.jelly file stored in a resource package named after the extension class.

When the configuration form is saved, Jenkins calls the extension constructor marked with the @org.kohsuke.stapler.DataBoundConstructor annotation, matching parameters by name

  • config.jelly options of your plugin. that will be shown in the action section for our plugin
Advertising

4.2.2 - Global.jelly

  • global.jelly options for Jenkins Global configuration page (that will be shown in the Manage Hudson/Configure System section)

<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson" xmlns:f="/lib/form">
  <f:section title="Hello World Builder">
    <f:entry title="French" field="useFrench"
      description="Check if we should say hello in French">
      <f:checkbox />
    </f:entry>
  </f:section>
</j:jelly>

4.2.3 - index.jelly

The index.jelly view file should render 1-2 paragraph worth of the detailed description of your plugin, perhaps with version numbers, link to the homepage, etc. This jelly script will be used in the plugin configuration page so that the user can learn more about a plugin.

4.2.4 - summary.jelly

<j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler"
         xmlns:d="jelly:define" xmlns:l="/lib/layout" xmlns:t="/lib/hudson"
         xmlns:f="/lib/form" xmlns:i="jelly:fmt">
    <t:summary icon="/plugin/myPluginName/icons/ico-48x48.png">
         My Summary information
    </t:summary>
</j:jelly>

4.3 - Help

  • help.html (main help file)
  • help-field.html (help for a field)

4.4 - Start the plugin

cd /path/To/MyRootPlugin
set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n
mvn hpi:run

If you open http://localhost:8080/jenkins in your browser, you should see the Jenkins page running in Jetty. The MAVEN_OPTS portion launches this whole thing with the debugger port 8000, so you should be able to start a remote debug session to this port from your IDE. See Enable Debugger on Maven

5 - Support

5.1 - Diagnostic

  • check jenkins.out and jenkins.err logs for any exceptions (such as malformed config.jelly)

5.2 - Check