Jenkins CI Plugin Fundamentals

Mads Nielsen, developer at Praqma 30. Oktober 2014

Overview. What will be covered● A brief introduction to the Jenkins object model.● A very brief explanation of the project lifecycle in

Jenkins.● Extension points, and a short demo with a concrete

implementation example.● How to get ‘inside’ the community. ● How to get help when you are stuck. ● How to finally release your own plugin

Object model @ a glance

Default Project lifecycle

Possible to extend and add to all parts of the jenkins lifecycle.

RecorderNotifier

Builder

BuildStep

Remoting and slaves

Extending Jenkins

What can you extend/add in Jenkins?● Security models/Credentials for specific tools● New types of views● View columns● Console annotators● Status widgets● New build steps● New post build steps● Listeners..● ...etc...Too much to list here

Describables● Describable objects usually have configuration elements

/ ui to be bound when the user interacts. ○ Example: Publisher, Builder, BuildWrapper

● Often has view elements attached, .jelly and .groovy views. Jenkins scans for specific names including:○ index○ floatingBox ○ summary

● The view files for each part you extend must be put in a package name whose name matches the FQCN.

Extension points

● Mark your class with the @Extension annotation to contribute.○ If the extension point is not a describable, there is no configurable ui

element. One example of such extension is the RunListener class

● You can define your OWN extension points, which lets other plugin extend your own plugin:○ Example: GitSCMExtension

Extension points: exampleUnprotectedRootAction - Contribute icon on left hand Jenkins menu bar@Extension

public class ConfigurationRotatorReport extends Actionable implements UnprotectedRootAction { }

Action

Persisting data, actions ● Use BuildAction(s) to contribute metadata to a run of a

particular project. ● Can contribute to the Jenkins UI for example when you

click a particular build, your plugin could create it’s own status page.

● Same rule applies, view file must match the FQCN of your action class.

Lessons learned...● By definition, unless otherwise specified, everything

happens on master when using Builder or Recorder….○ Remember to delegate when you’re supposed to work on the remote

using 1 of the following:■ Callable<T> of FileCallable<T> for complex operations where the workspace needs

to be manipulated■ Launcher for simple command line invocations

● Always test/try your plugins using slaves…● Serializable data!

Demo!This quick demo will show how we put the mentioned object model and topics so far explained into effect...and a few other interesting tidbits.

● A die roll game in Jenkins!● Demonstrates how to set the result of a build● Interacting with parameters when the build is

parameterized● git clone git@github.com:Praqma/CodeCamp.git”

Getting your plugin published1. Create a repository on GitHub.org. Add your source code to the repository.

2. Create a jenkins-ci accounta. https://jenkins-ci.org/account/

3. Sign up on the jenkins-ci dev mailing list.a. http://jenkins-ci.org/content/mailing-lists

4. Ask on the mailing list to get your plugin forked to the jenkins-ci group on github. a. Include a description in your mail of your pluginb. Add a readme.md to the root of your github repository to autogenerate descriptionc. The Jenkins mailing list lieutenants will create the wiki and jira components for you

5. When that is done...it’s time to get maven started.

Releasing plugins● “mvn release:prepare release:perform -Dusername=.. -Dpassword=..”

If your github userid/password do not match your jira/confluence userid/password….you need to add this to your settings.xml for maven

<settings xmlns= "http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation=" http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">

<servers>

<server>

<id>maven.jenkins-ci.org</id> <!-- For parent 1.397 or newer; before this use id java.net-m2-repository -->

<username>...</username>

<password>...</password>

</server>

</servers>

</settings>

● https://wiki.jenkins-ci.org/display/JENKINS/Hosting+Plugins#HostingPlugins-Releasingtojenkinsci.org

Releasing plugins..continuedOnce you have successfully executed mvn release:prepare release:perform. And a Jenkins lieutenant has created your jira component...you should now have a wiki for your plugin.● https://wiki.jenkins-ci.org/display/JENKINS/<your plugin-

name>+PluginRemember to keep your wiki page updated, with patch notes and changelogs.

Help! My plugin doesn’t work!

● The dev list is very active...so just ask○ http://jenkins-ci.org/content/mailing-lists

● The best way to learn how to program and create jenkins plugins is to open and explore other plugins.

● For a complete list of plugins and what extension points they use:○ https://wiki.jenkins-ci.org/display/JENKINS/Extension+points

Resources Summary● https://wiki.jenkins-ci.org/display/JENKINS/Extension+points● https://wiki.jenkins-ci.org/display/JENKINS/Hosting+Plugins● https://jenkins-ci.org/account/● http://jenkins-ci.org/content/mailing-lists● https://wiki.jenkins-ci.org/display/JENKINS/Plugin+tutorial#Plugintutorial-DebuggingaPlugin

Issue tracker● https://issues.jenkins-ci.org/secure/Dashboard.jspa

Demo project● https://github.com/Praqma/CodeCamp

Once the demo projected has been cloned to your machine, you can start an instance of jenkins with the plugin running by doing “mvn hpi:run” in the project root directory.

Thank you for listening