IRCBot Plugin

Introduction

This plugin enables Jenkins to send build notífications via IRC and lets you interact with Jenkins via an IRC bot. Like some other IM protocol plugins, for most of the common IM capabilities it relies on the instant-messaging-plugin

Among many other abilities, it can be used for hands-off notifications about build status changes with a globally configured IRC channel subscription, in both legacy freestyle jobs and newly with pipelines as an ircNotify step.

Interesting usage examples for the pipeline step include:

• ircNotify() to alert default subscribed channels per global config, using common notification strategies to filter messages about newly introduced failures and fixes (the empty parenthesis mean to use the default settings, very simply to code)

• ircNotify targets: "username #channelname" to alert certain recipients (in particular, certain users via private chats) - note that the list gets built into the job configuration rather than default subscribed channels

• ircNotify customMessage: "Some text", targets: "adminname" to always post the specified string

• Note: due to constraints of the current implementation, please use a special form of notification for reporting a start of pipeline build: ircNotify notifyOnStart:true otherwise the step is treated as a build completion notification with a NOT BUILT status (before some verdict becomes available).

Installation Requirements

Features

See the required instant-messaging-plugin for a description of protocol-independent features.

IRC-specific features

• support password-protected chatrooms

• support NickServ authentication

• the rate at which messages are send is throttled to one every 500ms to avoid being subject of flood control on the IRC server.
  This rate can be configured with the system property hudson.plugins.ircbot.messageRate

Pipeline syntax features

Starting with release 2.31 this plugin can be called as a pipeline step. The same toggles as configurable in a legacy job post-build task can be specified as named arguments to the pipeline step, with a difference that they are executed at once.

Example pipeline steps

Example ircNotify pipeline step syntax variants (not exhaustive):

pipeline {
    agent any
    options {
        disableConcurrentBuilds()
        skipDefaultCheckout()
    }
    stages {
        stage ('Notify') {
            steps {
// Notify a start of build; appends the extra message at the end (note: prefix with separators if needed)
                ircNotify notifyOnStart:true, extraMessage: "Running IRCBot test..."
            }
        }

        stage ('PM') {
            steps {
// Post a verbatim custom message; can specify non-default targets (defaults are in global config)
                ircNotify targets: "jim #myroom", customMessage: "Hello from IRCBot"
            }
        }
    }
    post {
        always {
// Notify the verdict only known at end of build; send to default targets by default notification strategy
//          ircNotify()
// ...or with a particular strategy:
            ircNotify notificationStrategy:"FAILURE_AND_FIXED"
        }
    }
}

with an output in the IRC room like the following:

(06:37:03) jenkins2: (notice) Starting build #214 for job GitOrg » reponame » branchname Running IRCBot test... (previous build: SUCCESS)
(06:37:04) jenkins2: (notice) Hello from IRCBot
(06:37:05) jenkins2: (notice) Project GitOrg » reponame » branchname build #214: SUCCESS in 7.2 sec: https://jenkins.localdomain/job/GitOrg/job/reponame/job/branchname/214/

Pipeline step arguments

The ircNotify step optionally accepts any of the following parameters, and effectively passes them to the instant-messaging-plugin for practical application.

argument name	syntax	description
targets	space-separated string	Send the notification (or a "customMessage") to specified user name(s) and channel name(s), the latter start with a hash sign.
notifyOnStart	boolean	Set to true explicitly in an ircNotify step reporting a start of build, instead of a build completion
notifySuspects	boolean	Select if the (build completion) notification should alarm the committers to (newly) failed builds
notifyCulprits	boolean	Specifies if culprits - i.e. committers to previous already failing builds - should be informed about subsequent build failures.
notifyFixers	boolean	Specifies if 'fixers' should be informed about builds they fixed.
notifyUpstreamCommitters	boolean	Specifies if upstream committers should be informed about build failures.
extraMessage	string	Append an additional message to usual notifications about build start/completion (note: you may want to start this string with a separator such as a semicolon)
customMessage	string	Instead of build status messages, send an arbitrary message to specified or default (global config) targets with the pipeline step (and ignoring the strategy and filtering rules options above)
notificationStrategy	string	https://github.com/jenkinsci/instant-messaging-plugin/blob/master/src/main/java/hudson/plugins/im/NotificationStrategy.java "ALL" - No matter what, notifications should always be sent. "ANY_FAILURE" - Whenever there is a failure, a notification should be sent. "FAILURE_AND_FIXED" - Whenever there is a failure or a failure was fixed, a notification should be sent. "NEW_FAILURE_AND_FIXED" - Whenever there is a new failure or a failure was fixed, a notification should be sent. Similar to FAILURE_AND_FIXED, but repeated failures do not trigger a notification. "STATECHANGE_ONLY" - Notifications should be sent only if there was a change in the build state, or this was the first build.

The following options can be specified, but not sure to what effect and how (TODO: try in practice and document here):

argument name	syntax	description
buildToChatNotifier	class name?	https://github.com/jenkinsci/instant-messaging-plugin/blob/master/src/main/java/hudson/plugins/im/IMPublisher.java#L88
matrixMultiplier	string or java/groovy token?	https://github.com/jenkinsci/instant-messaging-plugin/blob/master/src/main/java/hudson/plugins/im/IMPublisher.java#L89 https://github.com/jenkinsci/instant-messaging-plugin/blob/master/src/main/java/hudson/plugins/im/MatrixJobMultiplier.java e.g. per MatrixJobMultiplier: ONLY_CONFIGURATIONS ONLY_PARENT ALL

Known Issues

Please look into the issue tracker for any open issues for this plugin.

Debugging Problems

If you experience any problems using the plugin please increase the log level of the logger hudson.plugins.ircbot to FINEST (see Logging), try to reproduce the problem and attach the collected logs to the JIRA issue.

If the bot does not respond to your queries in IRC chat, make sure you are using the correct "Command prefix" if one is set up (see your $JENKINS_URL/configure ⇒ IRC Notification ⇒ Advanced), e.g.

!heyJenkins cb

…​and also that you are asking on the channel which is not marked "Notification only", and not e.g. in a private chat when only a channel connection is configured and you "Disallow Private Chat" in the Advanced configuration section. Note that per currently open issues, you may have to use the command prefix in a private chat as well.