Jenkins Plugin Development

Maven settings file

Depending on your current operating system, you will need to create/edit the .m2/settings.xml file. Windows users will find the settings.xml file by issuing the following command in Command Prompt:

echo %USERPROFILE%\.m2\settings.xml

Mac operating system users can edit/create the settings.xml file in ~/.m2/settings.xml.

Note that the settings element in the settings.xml file contains elements used to define values that configure Maven execution in various ways, such as pom.xml. However, these should not be bundled to any specific project or distributed to an audience, as they include values such as the local repository location, alternate remote repository servers, and authentication information.

Place the following content into the settings.xml file:

HelloWorld Jenkins plugin

In order to create a Jenkins plugin, you will need to use Maven archetypes, which you can read about  at https://maven.apache.org/guides/introduction/introduction-to-archetypes.html. Issue the following command in order to generate a Jenkins Hello World plugin:

mvn archetype:generate -Dfilter=io.jenkins.archetypes:hello-world

Here is a sample running session:

Notice here that 1 is entered for the archetype, a plugin version of 4 is chosen, and a value of jenkins-helloworld-example-plugin is defined. Hit Enter for the default values:

If all goes successfully, you should get the output of BUILD SUCCESS in Command Prompt.

You need to make sure that you can build your Jenkins plugin, so make sure to run the following command in Command Prompt:

// First go into the newly created directory
cd jenkins-helloword-example-plugin
// Then run the maven build command
mvn package

The mvn package command will create a target directory and run any tests that you have created in the directory:

As you can see, the Jenkins archetype actually created some tests for the Hello World Jenkins plugin example.

Folder layout explanation

The following is a screenshot of the newly created jenkins-helloworld-example-plugin directory:

The src directory contains the source files for the Jenkins plugin as well as tests for the plugins.

The target directory is generated with the mvn package. There is also a pom.xml file, which Maven created when you ran the archetype sub-command.

A Project Object Model (POM) is the fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project. It contains default values for most projects. Examples for this include the build directory, which is target, the source directory, which is src/main/java, and the test source directory, which is src/test/java.

Jenkins plugin source code explanation

As mentioned earlier, the src directory contains the source files for the Jenkins plugin. Notice that Maven created a rather long directory structure, which is common, and, as such, the directory structure for the helloworld plugin is ./src/main/java/io/jenkins/plugins/sample/HelloWorldBuilder.java. The test file itself is in ./src/test/java/io/jenkins/plugins/sample/HelloWorldBuilderTest.java.

Here’s the source code for the HelloWorldBuild.java class here:

package io.jenkins.plugins.sample;

import hudson.Launcher;
/* More Import Statements Here */

public class HelloWorldBuilder extends Builder implements SimpleBuildStep {

    /* Rest of methods in Github Source */

    @Override
    public void perform(Run<?, ?> run, FilePath workspace, Launcher launcher, TaskListener listener) throws InterruptedException, IOException {
       if (useFrench) {
            listener.getLogger().println("Bonjour, " + name + "!");
        } else {
            listener.getLogger().println("Hello, " + name + "!");
        }
    }
    @Symbol("greet")
    @Extension
    public static final class DescriptorImpl extends BuildStepDescriptor<Builder> {
        /* Rest of the source in Github */
}

Notice that the HelloWorldBuilder class extends the Builder class, which is a Jenkins core class. Also notice that you’re using a class called BuildStepDescriptor, which is also a Jenkins class. The source code for this file can be seen in the GitHub repository called jenkins-plugin-example in theHelloWorldBuilder.java (https://github.com/jbelmont/jenkins-plugin-example/blob/master/src/main/java/io/jenkins/plugins/sample/HelloWorldBuilder.java) file.

For the test cases in HelloWorldBuilderTest.java,  use JUnit, which is a popular unit testing library for the Java programming language:

package io.jenkins.plugins.sample;
import hudson.model.FreeStyleBuild;
/* More Import Statements Here */
public class HelloWorldBuilderTest {
@Rule
public JenkinsRule jenkins = new JenkinsRule();
    final String name = "Bobby";
@Test
public void testConfigRoundtrip() throws Exception {
        FreeStyleProject project = jenkins.createFreeStyleProject();
project.getBuildersList().add(new HelloWorldBuilder(name));
project = jenkins.configRoundtrip(project);
jenkins.assertEqualDataBoundBeans(new HelloWorldBuilder(name), project.getBuildersList().get(0));
}
    /* More test Cases in this file. */
}

The above Java test file has annotations such as @Rule, @Override, @Test, and @DataBoundSetter, which are a form of metadata providing data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate. You can find the source code for this file in the GitHub repository called jenkins-plugin-example in the HelloWorldBuilderTest.java file (https://github.com/jbelmont/jenkins-plugin-example/blob/master/src/test/java/io/jenkins/plugins/sample/HelloWorldBuilderTest.java ).

Building a Jenkins plugin

In order to build a Jenkins plugin, you need to run the mvn install command in the plugin directory.

The mvn install command will both build and test the Jenkins plugin and, more importantly, create a file called pluginname.hpi. In this case, it will create a file called jenkins-helloworld-example-plugin.hpi in the target directory that you can use to deploy to Jenkins.

Here’s a sample install run:

Installing a Jenkins plugin

Now, in order to install a newly built and installed HelloWorld example plugin, you’ll need to go to the Jenkins Dashboard | Manage Jenkins | Manage Plugins view and then click the Advanced tab. You can also directly go to the plugin section by going to scheme://domain/pluginManager. Alternately, if you’re running Jenkins locally, just go to http://localhost:8080/pluginManager/.

Then ensure to click the Advanced tab or go to http://localhost:8080/pluginManager/advanced:

You’ll then need to go to the Upload Plugin section:

Click Choose File and then find the newly created Helloworld Jenkins plugin, which should be in the directory:

jenkins-helloworld-example-plugin/target/jenkins-helloworld-example-plugin.hpi

Then click the Upload button.

The following is a screenshot of the newly installed Helloworld example plugin:

Guest Author— Jean-Marcel Belmont

Jean-Marcel Belmont is the author of Hands-On Continuous Integration and Delivery.