Getting Started With Ruby Plugins
Clone this wiki locally
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
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
or other ruby executables will be executing with JRuby as their
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.
jpi tool can build out the basic structure of this plugin
for us with the
$ 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
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
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 <firstname.lastname@example.org>" # 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
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.