Skip to content
This repository has been archived by the owner on Jan 25, 2022. It is now read-only.

Getting Started With Ruby Plugins

Jump to bottom
mainframer edited this page May 27, 2015 · 10 revisions

Getting Started Developing Ruby Plugins

This is a short tutorial covering the basics of Jenkins Ruby plugin development. You will learn how to create a new plugin project, and run it inside a test Jenkins server, as well as understand how the different pieces of your plugin work together by creating a native plugin to build gems.

Setting up your environment

JRuby 1.6+

Jenkins Ruby plugins use JRuby to access the Jenkins server runtime environment. The recommended way to install this is via rvm. All of the examples in this tutorial assume JRuby, and all invocations of the commands ruby or gem or other ruby executables will be executing with JRuby as their interpreter.

Jenkins Ruby Plugin Tools

Your primary tool for plugin development is the jpi command, which stands for Jenkins Plug In tool. It is used to generate boilerplate extensions, start your test server, package your plugin, and eventually, when it is ready for mass consumption, upload it to the Jenkins update center for distribution to the world.

Install it via rubygems:

gem install jpi

Confirm that it's working by accessing the help:

$ jpi -h
jpi - tools to create, build, develop and release Jenkins plugins

Usage: jpi command [arguments] [options]

Commands:
  jpi help [COMMAND]                  # get help for COMMAND, or for jpi itself
  jpi new NAME                        # create a new plugin called NAME
  jpi generate [options] [arguments]  # add new classes/templates and views t...
  jpi build                           # build plugin into .hpi file suitable ...
  jpi server                          # run a test server with plugin
  jpi release                         # release to jenkins-ci.org
  jpi version                         # show jpi version information

Great, you're ready to start writing Ruby plugins!

Creating a new plugin

In this tutorial we're going to write a simple plugin for building rubygems.

Our jpi tool can build out the basic structure of this plugin for us with the new command:

$ jpi new gembuilder
      create  gembuilder/README.md
      create  gembuilder/Gemfile
      create  gembuilder/gembuilder.pluginspec

As the output shows, it created a directory for our plugin and placed 3 files in there. Let's have a look at the Gemfile first:

source :rubygems

gem "jenkins-plugin-runtime", "~> 0.1.24"

The gems listed in this Gemfile will be bundled along with your plugin and loaded into your JRuby environment. We start out with just a single dependency which is the Jenkins Ruby API.

This library contains all the Ruby code that interfaces with the Jenkins Java runtime. You will be extending and including classes and modules from this library in order to write your Ruby plugin. Things like Build and Publisher and other players participate in this dance.

The second file is gembuilder.pluginspec and it contains metadata about the plugin required to use it and share it:

Jenkins::Plugin::Specification.new do |plugin|
  plugin.name = "gembuilder"
  plugin.display_name = "Gembuilder Plugin"
  plugin.version = '0.0.1'
  plugin.description = 'enter description here'

  # You should create a wiki page for your plugin when you publish it, see
  # https://wiki.jenkins-ci.org/display/JENKINS/Hosting+Plugins#HostingPlugins-AddingaWikipage
  # This line makes sure it's listed in your POM.
  plugin.url = 'https://wiki.jenkins-ci.org/display/JENKINS/My+Plugin'

  # The first argument is your user name for jenkins-ci.org.
  plugin.developed_by "cowboyd", "Charles Lowell <[email protected]>"

  # This specifies where your code is hosted.
  # Alternatives include:
  #  :github => 'myuser/my-plugin' (without myuser it defaults to jenkinsci)
  #  :git => 'git://repo.or.cz/my-plugin.git'
  #  :svn => 'https://svn.jenkins-ci.org/trunk/hudson/plugins/my-plugin'
  plugin.uses_repository :github => 'my-plugin'

  # This is a required dependency for every ruby plugin.
  plugin.depends_on 'ruby-runtime', '0.8'

  # This is a sample dependency for a Jenkins plugin, 'git'.
  # plugin.depends_on 'git', '1.1.11'
end

If this looks familiar to you, it's because it follows the .gemspec pattern established by Rubygems back in the nineties.

Generating a Builder

To implement our gem builder we'll again use the jpi command to generate the boilerplate for us.

jpi generate builder pull_request

Running a server and seeing your work

At any point during the development, you can run your work in progress inside Jenkins to inspect how/if it works. To do this, use the jpi server command, which starts Jenkins from your console. When Jenkins is ready, access http://localhost:8080/ with a browser.

Jenkins run in this mode has a few additional functionalities enabled for interactive development, such as an ability to reload all the source files. Views are also reloaded automatically as you change them, so this is a handy mode to interactively write views with trial-and-error.

Packaging a plugin binary

When you are happy with your changes, package the plugin into a .jpi file so that it can be deployed into your (and others') production Jenkins instances. Use the jpi build command to do this, which generates pkg/*.jpi.

Sharing your plugin with the community

Since you come up with an useful plugin, please consider sharing that with the community. This enables others to benefit from your work, and you benefit from more eyeballs and commits that they make. See The Jenkins community Wiki for how to request a hosting, then use the jpi release command to upload your plugin into the Jenkins community update center.

Clone this wiki locally