Preparing for Plugin Development

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

Download and install a JDK

Jenkins is based on Java, so to build Jenkins plugins you need to install a Java Development Kit (JDK). Java 17 is the version we recommend to users, so that’s what we’re using in this tutorial.

You can download and install Java 17 from the Eclipse Temurin website.

Many Linux distributions provide packages for Java for an easier install and upgrade experience. Consult your distribution’s documentation for details. To check if you have Java already installed, run java -version on a command prompt.

Install Apache Maven

Jenkins plugins are built with Apache Maven.

Download Maven from the Apache Maven website. Make sure to download one of the binary archives (with bin in their name).

Many Linux distributions provide packages for Maven for an easier install and upgrade experience. Consult your distribution’s documentation for details. On macOS, the Homebrew package manager offers Maven packages. Make sure a recent version of Maven 3, ideally 3.8.6 or newer, is provided if you decide to go this route.

Next, you will need to extract Maven and take note of its location. When you extract the Maven files, make sure you extract them directly into the target directory. For example, extract the files straight into C:\Program Files (x86)\Maven; do not extract the files to a different location and then copy the files.

Then, add the full path of the bin/ subdirectory extracted (for example, ~/Applications/apache-maven/bin or C:\Program files\Maven\bin) to the PATH variable in your OS. This will let you invoke Maven using mvn.

The rest of the tutorial assumes that Maven is on your PATH environment variable.

Configure Apache Maven

Apache Maven needs to be configured for Jenkins plugin development. The hpi plugin for Apache Maven requires some additional global configurations to function correctly with older Jenkins plugin environments.

Improper configuration settings can cause Maven to report errors or warnings, including failure to download artifacts during the update process. To avoid issues, include the following content in the settings.xml file in your ~/.m2 directory (Windows users will find them in %USERPROFILE%\.m2\settings.xml):

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <pluginGroups>
    <pluginGroup>org.jenkins-ci.tools</pluginGroup>
  </pluginGroups>
  <profiles>
    <profile>
      <id>jenkins</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <repository>
          <id>repo.jenkins-ci.org</id>
          <url>https://repo.jenkins-ci.org/public/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>repo.jenkins-ci.org</id>
          <url>https://repo.jenkins-ci.org/public/</url>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>

To verify that Maven is installed, run the following command:

mvn -version

This command prints some diagnostic output, including the versions of Java and Maven, and which Java installation was found by Maven. It should indicate a 17 version of Java, and list the path to where Java is located. If you don’t see this information, see Troubleshooting.

Setting up a productive environment with your IDE

IntelliJ IDEA

IntelliJ users just need to open the project and all should work out of the box.

You are advised to use the IntelliJ IDEA plugin for Jenkins Development, features it provides can be found in its documentation.

You can create a new plugin using one of the Jenkins plugin archetypes. Create a new Maven project using Create from archetype and Add an Archetype. Select the GroupId and ArtifactId as above, and choose RELEASE as version. On the next screen, select io.jenkins.plugins as groupID and choose an artifactId (Project name) and Version to your liking. This will automatically create a maven project based on the specified artifact (for example, empty-plugin).

NetBeans

NetBeans users can use the IDE’s Maven support to open the project directly.

As you navigate through the code, you can tell NetBeans to attach source code JAR files by clicking the "Attach" button that appears in the top of the main content window. This allows you to read the Jenkins core source code as you develop plugins. (Or just select Download Sources on the Dependencies node.)

You are advised to use the NetBeans plugin for Jenkins/Stapler development. This offers many Jenkins-specific features. Most visibly, create a new plugin using New Project » Maven » Jenkins Plugin, and use Run project to test it.

Eclipse

Open the project as an existing Maven Project.

Next step

Create and build your first Jenkins plugin.

Troubleshooting

Anything not working for you? Ask for help on our community forum community.jenkins.io or on the jenkinsci-dev mailing list.