This document, together with the hello-world plugin, shows you how to get started with the plugin development.
Jenkins defines extensibility points, which are interfaces or abstract classes that model an aspect of a build system. Those interfaces define contracts of what need to be implemented, and Jenkins allows plugins to contribute those implementations. See this document for more about extension points.
In this document, we'll be implementing a Builder that says hello. (built-in builders include Ant, Maven, and shell script. Builders build a project.)
To develop a plugin, you need Maven 3 (why?) and JDK 6.0 or later. If this is the first time you use Maven, make sure Maven can download stuff over the internet.
If you are using the Nexus Maven Repository Manager, you can ignore these instructions, and instead, click here for instructions on how to add Jenkins build prerequisites and the proper
It may be helpful to add the following to your
~/.m2/settings.xml (Windows users will find them in
<settings> <pluginGroups> <pluginGroup>org.jenkins-ci.tools</pluginGroup> </pluginGroups> <profiles> <!-- Give access to Jenkins plugins --> <profile> <id>jenkins</id> <activation> <activeByDefault>true</activeByDefault> <!-- change this to false, if you don't like to have it on per default --> </activation> <repositories> <repository> <id>repo.jenkins-ci.org</id> <url>http://repo.jenkins-ci.org/public/</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>repo.jenkins-ci.org</id> <url>http://repo.jenkins-ci.org/public/</url> </pluginRepository> </pluginRepositories> </profile> </profiles> <mirrors> <mirror> <id>repo.jenkins-ci.org</id> <url>http://repo.jenkins-ci.org/public/</url> <mirrorOf>m.g.o-public</mirrorOf> </mirror> </mirrors> </settings>
This will let you use short names for Jenkins Maven plugins (i.e. hpi:create instead of org.jenkins-ci.tools:maven-hpi-plugin:1.61:create),
though this is unnecessary once you are already working in a plugin project (only useful for initial hpi:create).
Note that adding the Jenkins repositories in a profile like this is not really necessary since most (all?) plugins already define these repositories.
And the mirror declaration is probably unnecessary.
To start a new plugin, use the online skeleton generator, or use an IDE (below).
Alternatively, if you are more comfortable with Maven, run the following command:
$ mvn -U org.jenkins-ci.tools:maven-hpi-plugin:create
This will ask you a few questions, like the groupId (the Maven jargon for the package name) and the artifactId (the Maven jargon for your project name), then create a skeleton plugin from which you can start with. Make sure you can build this:
$ cd newly-created-directory $ mvn package
-U means that Maven should update all relevant Maven plugins (check for plugin updates)
hpi: this prefix specifies that the Jenkins HPI Plugin is being invoked, a plugin that supports development of Jenkins plugins
create is the goal which creates the directory layout and the POM for your new Jenkins plugin and it adds it to the module list
package is a standard phase which compiles all sources, runs the tests and creates a package - when used by the HPI plugin it will create an
To build a plugin, run
mvn install. This will create the file
./target/pluginname.hpi that you can deploy to Jenkins.
$ mvn install
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.
IntelliJ 7.0 (or later) users can load pom.xml directly from IDE, and you should see all the source code of libraries and Jenkins core all the way to the bottom.
IntelliJ defaults to downloading sources and JavaDocs on demand. So, to see the source, you may need to click the
Use Eclipse Juno (4.2) or later for the best experience.
As Jenkins plugins are Maven projects, Eclipse users have two ways to load a Jenkins plugin project. One is to use m2e, which tries to make Eclipse understand Maven "natively", and the other is to use Maven Eclipse plugin, which makes Maven generate Eclipse project definitions. At the moment, unless you have some prior experience with m2e, we currently recommend plugin developers to go with the Maven Eclipse plugin.
Eclipse users can run the following Maven command to generate Eclipse project files (the custom outputDirectory parameter is used to work around the lack of JSR-269 annotation processor support in Eclipse:)
$ mvn -DdownloadSources=true -DdownloadJavadocs=true -DoutputDirectory=target/eclipse-classes eclipse:eclipse
Once this command completes successfully, use "Import..." (under the File menu in Eclipse) and select "General" > "Existing Projects into Workspace".
Do not select "Existing Maven Projects", which takes you to the m2e route
See Jenkins plugin development with Eclipse for gotchas and other known Eclipse/Maven related issues with Jenkins plugin development.
The plugin workspace consists of the following major pieces:
Maven uses it for building your plugin.
Java source files of the plugin.
Jelly/Groovy views of the plugin. See this document for more about it.
Static resources of the plugin, such as images and HTML files.
Let's take a look at the source code. A plugin's main entry point is a PluginImpl class that extends from Plugin. Once Jenkins detects your plugin class (via its inheritance relationship from
Plugin), it will create an instance, and invoke methods. A Plugin class is optional; a plugin may simply implement extensions:
Most of the time, a plugin class just registers extension points, and your main work involves implementing those extension points. See the source code for more about how a
Builder is implemented and what it does.
NetBeans 6.7+ users can just hit Debug. For all others, run the following command to launch Jenkins with your plugin:
$ export MAVEN_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n" $ mvn hpi:run
> set MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n > mvn hpi:run
If you open
http://localhost:8080/ 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 debug session to this port from your IDE.
Once this starts running, keep it running. Jetty will pick up all the changes automatically.
src/main/resourcesor resource files in
src/main/webapp, just hit F5 in your browser to see the changes.
MAVEN_OPTS can be used to specify all sorts of other JVM parameters, like
If you need to launch the Jenkins on a different port than 8080, set the port through the system property
$ mvn hpi:run -Djetty.port=8090
maven-hpi-plugin 1.65 or later (used by parent POM 1.401 or later) can set the context path by using a system property.
$ mvn hpi:run -Dhpi.prefix=/jenkins
To create a distribution image of your plugin, run the following Maven command:
$ mvn package
This should create
target/*.hpi file. Other users can use Jenkins' web UI to upload this plugin to Jenkins (or place it in
If you got to this point, you should definitely consider hosting your plugin on jenkins-ci.org. Move on to this document for how to do that. This includes the instructions for releasing the plugin.
If you are building a patched version of one of the plugins in the Jenkins core, the deployment process is a bit different. This is because Jenkins will itself manage these plugins unless you tell it not to.
mvn -o ...to avoid hitting repositories every time. This will make various operations considerably faster.
mvn cleanonce, in particular to delete
target/workthat Jetty uses. Newer versions may just use work, not target/work. Otherwise your Jetty may continue to pick up old left-over JAR files.
Besides this tutorial, there are other tutorials and examples available on line: