Create a Plugin

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

After preparing your environment, the next step is to create a new plugin.

If your intention is to publish your plugin on the Jenkins update site, now is a good time to look for plugins that already do something similar. See this wiki page for more information.

Create the Project Layout with Sample Plugin Archetype

Open a command prompt, navigate to the directory you want to store your new Jenkins plugin in, and run the following command:

mvn -U archetype:generate -Dfilter=io.jenkins.archetypes:

This command will let you generate one of several project archetypes related to Jenkins. In this tutorial we’re going to use the hello-world archetype, so select the most recent version of that archetype:

mvn -U archetype:generate -Dfilter=io.jenkins.archetypes:
…
Choose archetype:
1: remote -> io.jenkins.archetypes:empty-plugin (Skeleton of a Jenkins plugin with a POM and an empty source tree.)
2: remote -> io.jenkins.archetypes:global-configuration-plugin (Skeleton of a Jenkins plugin with a POM and an example piece of global configuration.)
3: remote -> io.jenkins.archetypes:global-shared-library (Uses the Jenkins Pipeline Unit mock library to test the usage of a Global Shared Library)
4: remote -> io.jenkins.archetypes:hello-world-plugin (Skeleton of a Jenkins plugin with a POM and an example build step.)
5: remote -> io.jenkins.archetypes:scripted-pipeline (Uses the Jenkins Pipeline Unit mock library to test the logic inside a Pipeline script.)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 4 (1)
Choose io.jenkins.archetypes:hello-world-plugin version:
1: 1.1
2: 1.2
3: 1.3
4: 1.4
5: 1.5
6: 1.6
7: 1.7
8: 1.8
9: 1.9
10: 1.10
11: 1.11
12: 1.12
13: 1.13
14: 1.14
15: 1.15
16: 1.16
17: 1.17
18: 1.19
19: 1.20
20: 1.21
21: 1.22
22: 1.23
23: 1.24
24: 1.25

Choose a number: 24: 24 (2)
…
[INFO] Using property: groupId = unused (3)
[INFO] Using property: package = io.jenkins.plugins.sample
[INFO] Using property: hostOnJenkinsGitHub = true
Define value for property 'artifactId': demo (4)
Define value for property 'version' 1.0-SNAPSHOT: : (5)
Confirm properties configuration:
groupId: unused
package: io.jenkins.plugins.sample
hostOnJenkinsGitHub: true
artifactId: demo
version: 1.0-SNAPSHOT
 Y: : y (6)
1 Enter the number for the hello-world-plugin archetype, 4 in this case.
2 This tutorial is based on version 1.25 of the hello-world-plugin archetype, so enter 24 to select it.
3 groupId uniquely identifies your project across all projects. A group ID should follow Java’s package name rules. This means it starts with a reversed domain name. For example: io.jenkins.plugins
4 artifactId is mandatory and uniquely identifies your plugin in Jenkins. It is the unique base name of the primary artifact being generated by this maven project. This plugin tutorial uses the name demo (user input highlighted in bold). If you want to publish your plugin, make sure the name is not already taken, and that the name you choose is future-proof: the artifactId cannot be changed after you’ve published your first release. Do not use the words jenkins or plugin in this ID—only the words describing what kind of Jenkins plugin this is.
5 There’s no need to choose a different version number here. This is the development version (indicated by SNAPSHOT) of version 1.0. Learn more about Maven version numbers.
6 After you enter all the values, Maven will show them again. Review and confirm your selection.

This creates a directory with the same name as the plugin’s artifactId (demo in this case), and adds the basic structure for a working plugin. Let’s make sure we can build the plugin:

mv demo demo-plugin (1)
cd demo-plugin
mvn verify
1 Maven has created the project structure in a directory with the same name as you chose for your plugin. We will rename the directory to match the conventional repository names used in the GitHub organization @jenkinsci.

Maven will download several more dependencies, and then go through the configured build lifecycle, including static analysis (Spotbugs) and tests, until it shows something like this:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  47.141 s
[INFO] Finished at: 2022-11-17T10:04:29-07:00
[INFO] ------------------------------------------------------------------------
To learn more about what’s involved in a plugin build, see Plugin Build Process.

Not the output you’re seeing? See the Troubleshooting section below.

Let’s run the plugin and see what it does.

Troubleshooting

Anything not working for you? Ask for help in chat or on the jenkinsci-dev mailing list.

archetype:generate hangs

If the archetype:generate command hangs, it could be because you are using a repository mirror. Try:

echo '<settings/>' > /tmp/empty.xml
mvn -s /tmp/empty.xml -U archetype:generate -Dfilter=io.jenkins.archetypes: