Groovy Events Listener Plugin

A Jenkins plugin, which executes Groovy code when an event occurs.

Table of contents

1. Overview
2. Building
3. Basic Usage
4. Authors
5. License
6. Similar Plugins
7. Releases (Release Notes, Changelog, Artifacts)
8. Issues (Bugs / Issues / Enhancements)

Overview

The reason I created the plugin was because I wanted to integrate Jenkins with an external application. Invoking a Jenkins jobs via the REST API was simple, but getting Jenkins to callback the external application wasn't straight forward.

All the plugins I'd seen either had to be individually configured per job (i.e. in a post build step), or their features were limited to making a HTTP GET/POST request (a bit restrictive).

Basically:

• I wanted to be able to write my own code
• I didn't want to repeat myself

So I wrote this plugin. Along the way, I realised it could have some other applications too:

• customised logging
• performance monitoring
• incident escalation
• integration with 3rd party applications
• much more...

Building

Prerequisites:

• JDK 11 (or above)

To setup for use with Intellij IDEA

./gradlew cleanIdea idea

To run Jenkins (http://localhost:8080) locally with the plugin installed:

./gradlew clean server

To build the Jenkins plugin (.jpi) file:

./gradlew clean jpi

To publish/release the Jenkins plugin:

1. Update the version in gradle.properties, to remove "-SNAPSHOT" (increment and re-add after publishing)

./gradlew clean publish

Basic Usage

To get started:

1. Install the plugin (or run Jenkins locally)
2. Navigate to the Jenkins > Manage Jenkins > Configuration page
3. You should now see a Global Events Plugin section (similar to the following screenshot).

This plugin executes the supplied Groovy code, every time an event is triggered.

So lets get started with the simplest example.

log.info "hello world!"

Now save the changes, kick off a Jenkins job, and you will see "hello world!" written to the logs three times. Alternatively, there's now a Test Groovy Code button, which will execute the code with the event=RunListener.onStarted.

The plugin actually injects a couple of variables, which you can use in your code. Here's some examples using the event and env variables.

This code limits the logging to only occur when a job is completed! N.B. this behaviour can also be replicated using the configuration options.

if (event == Event.JOB_STARTED) {
    log.info "hello world!"
}

And this one filters on jobs whose name starts with "Foobar":

if (env.JOB_NAME.startsWith('Foobar')) {
    log.info "hello world!"
}

There is also a context variable of type Map. You can add your own entries to it, by returning a Map from your code. E.g.

if (event == Event.JOB_FINALIZED) {
    def newCount = (context.finishCount ?: 0) + 1
    log.info "hello world! finishCount=$newCount"
    return [finishCount: newCount]
}

This will keep a record in memory, of how many times jobs have finished. You can achieve the same result by adding variables directly to the context variable:

if (event == Event.JOB_FINALIZED) {
    context.finishCount = (context.finishCount ?: 0) + 1
    log.info "hello world! finishCount=${context.finishCount}"
}

You can also use @Grab annotations if you'd like to import external dependencies (thanks Daniel for your solution!).

@Grab('commons-lang:commons-lang:2.4')
import org.apache.commons.lang.WordUtils
log.info "Hello ${WordUtils.capitalize('world')}!"

Not bad! And finally, you can import Groovy scripts, so you can hide away some of the heavy lifting. Here I'm using a RestClient.groovy script.

def client = evaluate(new File('../includes/RestClient.groovy'))

def resp = client.post('http://localhost:9200/jenkins/runInstances', [
        jobName       : env.JOB_NAME,
        jobDuration   : run.duration,
        jobResult     : run.result.toString(),
        jobBuildNumber: run.number,
        jobTimestamp  : run.timestamp.timeInMillis,
])
assert resp.status == 201

You can pretty much do whatever you want from here: custom logging to a file, sending performance metrics to a server, sending email or messenger notifications, calling a SOAP service... The world's your oyster. If you've got something cool that you want to share, let me know and I'll add it to the examples!

For more details on which events trigger the code, what variables are available and details on configuring logging, please see the plugin's help file.

Authors

Marky Jackson [email protected]

License

Licensed under the MIT License (MIT)

Similar Plugins

These plugins have similar (but different) functionality:

• https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin
• https://wiki.jenkins-ci.org/display/JENKINS/Extreme+Notification+Plugin
• https://github.com/speedledger/elasticsearch-jenkins
• https://github.com/jenkinsci/post-completed-build-result-plugin