Plugin Information |
---|
View IRC on the plugin site for more information. |
Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:
Installation Requirements
This plugin needs the instant-messaging plugin. Please ensure that the latest version of this plug-in is also installed.
Features
See the 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() } } }
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 fixed builds. |
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 it with a separator like 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) |
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? | |
notificationStrategy | string or java/groovy token? |
|
matrixMultiplier | string or java/groovy token? | e.g. 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.
Changelog
Version 2.31 (2019-08-09)
https://github.com/jenkinsci/ircbot-plugin/compare/ircbot-2.30...jenkinsci:ircbot-2.31
- Added a Jenkinsfile to CI-test the plugin itself: https://github.com/jenkinsci/ircbot-plugin/pull/19
- Non-functional whitespace, javadoc and style fixes in the codebase for better maintainability: https://github.com/jenkinsci/ircbot-plugin/pull/20
- Added pipeline support to match capabilities of instant-messaging-plugin release 1.36 (not fully published) and 1.37: https://github.com/jenkinsci/ircbot-plugin/pull/21 and then 1.38: https://github.com/jenkinsci/ircbot-plugin/pull/23
- So now there is an
ircNotify()
step with numerous supported options (or default activity if none are passed) forJenkinsfile
scripts!
- So now there is an
- Added a
customMessage
option to instantly post the specified message to specified IM target(s) as the payload of a step (not tied into notification strategies for build start/completion): part of https://github.com/jenkinsci/ircbot-plugin/pull/21 - Note that currently there is special syntax for build-start notifications from a pipeline step (e.g.
ircNotify notifyOnStart:true
) which is intended as a temporary solution to the problem of not having support for an IM-specificoptions{...}
setting in pipelines yet, and so reporting "NOT BUILT" (completion-notification mode) if there was no verdict yet
Version 2.30 (2017-08-25)
- A rapid series of releases (2.28, 2.29, 2.30) led up to addition of SASL in PircBotX, and some warnings fixes
Version 2.27 (2016-03-03)
- Bump of PircBotX and other dependencies versions
Version 2.26 (2015-02-19)
- don't make concurrent builds wait for the previous build (with instant-messaging-plugin 1.33) JENKINS-26892
- make delay between messages configurable via system property "hudson.plugins.ircbot.messageRate"
- try to connect to NickServ protected up to 2 minutes in case NickServ is reacting very slowly
Version 2.25 (Apr 2, 2014)
- Fixed a NullPointerException introduced in 2.24 JENKINS-22478
Version 2.24 (Mar 29, 2014)
- Added basic support for SOCKS proxies (thanks Andrew Bonney)
- Fixed: dropped whitespace if IRC colors were used JENKINS-22360 (thanks Marius Gedminas)
- Updated to PircBotX 1.9
Version 2.23 (May 22, 2013)
- new option to disallow bot commands from private chats
- new option to trust self-signed SSL certificates
Version 2.22 (Mar. 1, 2013)
- fixed a problem with reconnects (JENKINS-17017)
- Update to PircBotX 1.8 (https://code.google.com/p/pircbotx/wiki/ChangeLog#1.8_-_January_11th,_2013)
Version 2.21 (Dec. 15, 2012)
- new option to colorize build notifications based on the build outcome.
Note that this feature may change in the future - especially regarding 'what' is colorized and the colors! - fixed issue #13967 (ArrayIndexOutOfBounds Exception when I try to setup a second IRC channel in Jenkins configuration)
Version 2.20 (Oct. 13, 2012)
- fixed a bug when updating from previous versions on Windows
Version 2.19
- See instant-messaging plugin 1.22 for new features. Also:
- Make IRC login name configurable JENKINS-14467
- Update to PircBotX 1.7
Version 2.18
- fixed: unable to connect to ircu servers JENKINS-11623
- See instant-messaging plugin 1.21 for more new features
Version 2.17
skipped
Version 2.16:
- fixed: password authentication not working since 2.14 (JENKINS-10862)
Version 2.15
- fixed: NickServ password wasn't saved (JENKINS-10145)
Version 2.14
- Support SSL connections (JENKINS-3543)
- Attention: as the underlying IRC library had to be replaced to achieve this, it's not completely unlikely that you could experience some regressions. Please open a new issue in that case.
- New option to specify IRC server encoding (JENKINS-10090)
Version 2.13
- See Instant-Messaging plugin 1.16 for new features
Version 2.12
- See Instant-Messaging plugin 1.15 for new features
Version 2.11
- see instant-messaging plugin 1.14 for changes!
Version 2.9
- wait 5 seconds after identifying with NickServ before trying to join channels. Should minimize problems if channels are restricted and the NickServ identification isn't fast enough before the bot tries to join the channels. Refs. JENKINS-6600 , JENKINS-8451
Version 2.8
- fixed: NullPointerException because of incorrect migration of old configurations. JENKINS-8001
- new feature: new chat notifier which prints the failing tests, too JENKINS-7035
Version 2.7
- improvement: bot commands are now extensible and open for other plugins (see class BotCommand).
- improvement: added an extension point to customize the message the bot sends to chats for notification (see class BuildToChatNotifier).
- improvement: bot may be invited to channels (issue 6600 )
Version 2.6
- fixed: disconnects (and no reconnects) when changing the global config (issue #6933)
- improved behaviour when plugin is disabled. I.e. doesn't log unnecessary stuff.
- fixed: plugins configure option not visible JENKINS-5978 JENKINS-5233
- use UTF-8 as encoding for sending/receiving messages (previously used default encoding of the Hudson server)
Version 2.5
- fixed: notify upstream commiter would have notified committers of 'old' builds (JENKINS-6712)
- improvement: print useful project names for matrix jobs (JENKINS-6560 )
- fixed: don't delay Hudson startup (JENKINS-4346 )
- feature: userstat command for bot (JENKINS-6147 )
- fixed: don't count offline computer for the executors count (JENKINS-6387)
Version 2.4
- fixed: bot output sometimes send to wrong user (JENKINS-6484)
Version 2.3
- allow to pass build parameters with the build command (JENKINS-5058 ) Make sure that instant-messaging 1.7 or later is installed.
- allow to set NickServ passwords
Version 2.2
- support password-protected chatrooms
Version 2.1
- new option to inform upstream committers (JENKINS-4629 )
- Bot uses /msg command to inform channels/users instead of /notice as before. You can restore the old behaviour in the global configuration. (JENKINS-5087 )
Version 2.0
- This is the first version which is build upon the instant-messaging plugin. Make sure that instant-messaging 1.3 is installed.
- This version needs Hudson 1.319 or newer
- Though much care has been taken to migrate settings from previous versions, because of the amount of the changes it cannot be guaranteed that all old settings are migrated correctly!
- This version supports all options that the Jabber plugin supports. See there for more info.
- Command responses are no longer send as private messages to the user. Instead they are send to the channel. If you want private messages then send the command as a private message to the bot.
Usage
When you install this plugin, your Hudson configuration page gets additional "IRC Notification" option as illustrated below:
In addition, each project should add a "Post-build Actions"> "IRC Notification" configuration as illustrated below:
For the project configuration, leave the Channels blank to default to the channels defined in the master IRC configration.