How to write a Jenkins Plugin – Part 4

In this part we’ll look at getting your plugin hosted on the Jenkins GitHub, performing a release, and documenting your plugin in the Jenkins wiki.

Your main point of reference for this should be the official guide in the Jenkins wiki at https://wiki.jenkins-ci.org/display/JENKINS/Hosting+Plugins which is much more detailed AND UP TO DATE – this post is now quite old so be sure to check the current official instructions.

Consider this guide a simple quick-start guide for complete beginners that gives an overview of the process so that you can see how it all hangs together. (There are a few things here that took me a while to figure out the first time round. I have a bad memory and I don’t like to have to figure things out more than once, so this is my reminder too.)

You may also find it useful to scan through this before you start development, to see how things like your plugin name and artifactId will get used.

User Accounts

You’re going to need accounts at:

It will be a lot easier if you make your Jenkins and GitHub accounts with the same username and password.

Request Hosting

Having joined the developer’s mailing list, you’ll need to post a message requesting hosting for your new plugin. You’ll see lots of other examples.

Make the subject clear, include your GitHub ID, give a brief explanation of the purpose of your plugin, and specify the plugin name.

The plugin name should be your project’s artifactId, with “-plugin” appended.

For example, my plugin’s artifactId is custom-view-tabs, so I requested hosting for custom-view-tabs-plugin, and in response the GitHub repository was created in the Jenkinsci GitHub as https://github.com/jenkinsci/custom-view-tabs-plugin

You should have commit access to your new repo. If you encounter problems when you try to push your changes then go back to the mailing list for help.

You can now add this rpeo as the remote for your project and push changes.

Create a Wiki Page

Log in with your Jenkins ID and add a new page under https://wiki.jenkins-ci.org/display/JENKINS/Plugins, for example I added https://wiki.jenkins-ci.org/display/JENKINS/Custom+View+Tabs+Plugin

Note that you don’t need to type the + signs when you create the page name.

To get the auto-generated plugin information section that details the versions, repository links, and download history for your plugin, you need to add a couple of tags like so, changing the pluginId to match your own plugin’s artificatId, and to provide a brief description for your plugin:

{jenkins-plugin-info:pluginId=custom-view-tabs}

{excerpt}
Custom View Tabs plugin allows customised labels and colours for view tabs, showing job status details.
{excerpt}

Don’t expect anything to actually show up in the plugin information section until long after you’ve actually performed a release. It was weeks before I saw anything.

The rest of the page is up to you!

Prepare the POM

There are some important things you need in your POM to make things work. Check the official guide for up to date details.

You must provide a url element giving the address of your wiki page:

<url>http://wiki.jenkins-ci.org/display/JENKINS/custom-view-tabs</url>

You should add a licenses section detailing whatever licence you have chosen to use.

You must add a developers section with your Jenkins / GitHub ID and email address.

You must provide the scm details matching your plugin’s GitHub repo, eg here’s what mine looks like:

 <scm>
  <connection>scm:git:ssh://github.com/jenkinsci/custom-view-tabs-plugin.git</connection>
  <developerConnection>scm:git:ssh://git@github.com/jenkinsci/custom-view-tabs-plugin.git</developerConnection>
  <url>https://github.com/jenkinsci/custom-view-tabs-plugin</url>
 </scm>

Perform a Release

When you’re all done, it’s time to release your plugin to the world. You simply do this with the standard Maven release process, and the Jenkins machinery takes care of making your plugin available to Jenkins users from the plugin installation page.

Check the official guide for up to date details, but essentially you need to run the following command with your Jenkins / GitHub credentials. (It’s a faff if you have used different credentials for the two accounts). The official guide currently says to run:

mvn release:prepare release:perform -Dusername=... -Dpassword=...

This only worked for me when I did it in two stages. First the release:prepare, and then the release:perform. I prefer to do it in two steps like this anyway.

If you’re a Windows user and used to running Maven commands from a command prompt, remember that this release process is going to involve Git, for example committing the updated version numbers. This means that your Git tool has to be visible, so you may want to do this from your Git shell instead.

Another thing that didn’t work for me this way was specifying the credentials on the command line. The official guide explains how to add your credentials to your settings.xml, and I had to do that for things to work. In your settings.xml add a server element with the id set to “maven.jenkins-ci.org” and your login credentials.

When I came to release a second version I had a load of trouble with failures relating to pushing tags to GitHub. It seemed to be credential related, and yet all my credentials were unchanged. Eventually I discovered 2 issues. First, I was behind a corporate firewall that seemed to be interfering. Second, I found that GitHub had suspended the SSH key I was using for this project, due to inactivity. I was so busy checking my user id and password for the fifteenth time that I never thought to also check the SSH key. If you get Git push failures during the release process, check your ssh keys at https://github.com/settings/ssh and try a network without a corporate firewall in the way.

Check it all worked

So, once you’ve run those commands and performed the release, what should you expect? How do you know if it has really worked?

There are a few places to check, some of which will only be updated after maybe half a day.

Starting at the very beginning in case you’re a complete beginner:

First, you should see the activity in your Github repo that was performed by the maven release plugin, eg a commit such as [maven-release-plugin] prepare for next development iteration.

Second, your plugin should eventually show up in the Jenkins update centre download section at http://updates.jenkins-ci.org/download/plugins/

Third, your plugin should eventually be listed in the Jenkins plugin releases RSS feed at http://feeds.feedburner.com/JenkinsPluginReleases

Finally, the next day you should start to see your plugin in the available downloads section of your manage Jenkins / install plugins page.

There’s another useful page at https://wiki.jenkins-ci.org/display/JENKINS/Unreleased+Plugin+Changes where you will be able to see any changes you have committed to your repository but not yet released.

And that’s all. Hope it made it a little easier for you to get started.

Hopefully I’ll find time to continue this series with some more detail about working with the Jenkins model. Watch this space.

Update

All plugins are built automatically at https://jenkins.ci.cloudbees.com/job/plugins/

Pushing changes in your GitHub repo will trigger a new build.

 

Advertisements
Posted in Jenkins, Jenkins Plugins
2 comments on “How to write a Jenkins Plugin – Part 4
  1. jrz says:

    Thank you so much for putting this up, it was all extremely helpful!

  2. erikzaadi says:

    Awesome, helped me a lot, thanks!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: