Hubot IRC Adapter

Travis-CI Build Status


Description

This is the IRC adapter for hubot. For discussion about this adapter, join #hubot-irc on irc.freenode.net. For convenience you can #hubot-irc using webchat.freenode.net/

Installation and Setup

To get your own hubot up and running we recommend following the Getting Started directions from the hubot wiki, they are summarized here:

% npm install -g yo generator-hubot
% mkdir myhubot
% cd myhubot
% yo hubot --adapter=irc
% HUBOT_IRC_SERVER=irc.freenode.net \
HUBOT_IRC_ROOMS="#myhubot-irc" \
HUBOT_IRC_NICK="myhubot" \
HUBOT_IRC_UNFLOOD="true" \
bin/hubot -a irc --name myhubot

Note: The default hubot configuration will use a redis based brain that assumes the redis server is already running. Either start your local redis server (usually with redis-start &) or remove the redis-brain.coffee script from the default hubot-scripts.json file.

Configuring the Adapter

The IRC adapter requires only the following environment variables.

* HUBOT_IRC_SERVER
* HUBOT_IRC_ROOMS
* HUBOT_IRC_NICK

And the following are optional.

* HUBOT_IRC_PORT
* HUBOT_IRC_USERNAME
* HUBOT_IRC_PASSWORD
* HUBOT_IRC_NICKSERV_PASSWORD
* HUBOT_IRC_NICKSERV_USERNAME
* HUBOT_IRC_SERVER_FAKE_SSL
* HUBOT_IRC_SERVER_CERT_EXPIRED
* HUBOT_IRC_UNFLOOD
* HUBOT_IRC_DEBUG
* HUBOT_IRC_USESSL
* HUBOT_IRC_PRIVATE
* HUBOT_IRC_USESASL

$3

This is the full hostname or IP address of the IRC server you want your hubot
to connect to. Make a note of it.

$3

This is a comma separated list of the IRC channels you want your hubot to join.
They must include the #. Make a note of them. You can join private channels
by simply appending the channel password to the room, e.g. #private password.

$3

This is the optional nick you want your hubot to join with. If omitted it will
default to the name of your hubot.

$3

This is the optional port of the IRC server you want your hubot to connect to.
If omitted the default is 6667. Make a note of it if required.

$3

This is the optional username and/or password of the IRC server you want your hubot to connect
to. If the IRC server doesn't require a username/password, this can be omitted. Make a
note of it if required.

$3

This is the optional Nickserv password if your hubot is using a nick registered
with Nickserv on the IRC server. Make a note of it if required.

$3

This is the optional Nickserv username if your hubot is using a nick registered
with Nickserv on the IRC server, e.g. /msg NickServ identify .

$3

This is the optional flag if you want to accept self signed SSL certificated
from a non trusted CA. You can set the variable to anything.

$3

This is the optional flag if you want to accept an expired SSL certificate.

$3

This is the optional flag if you want to protect your hubot from flooding
channels with messages. It will queue messages and slowly send. You can set the
variable to any truthy value or a number; if a number is given we will interpret it as
a wait time in milliseconds to use between sending messages.

$3

This is the optional flag which will display debug output. You can set the
variable to anything.

$3

This is the optional flag if your hubot is connecting to an IRC server using
SSL. You can set the variable to anything.

$3

This is the optional flag if your hubot should ignore PRIVMSG and INVITE
commands. You can set the variable to anything.

$3

SASL is a method that allows identification to services (NickServ) during the connection
process, before anything else happens - therefore eliminating the need to /msg nickserv identify.
Note: May be a requirement from some IRC hosts (freenode) when connecting from a public cloud provider (AWS).

$3

% heroku config:add HUBOT_IRC_SERVER="..."

% heroku config:add HUBOT_IRC_ROOMS="#foo,#bar"

Optional

% heroku config:add HUBOT_IRC_NICK="..."

% heroku config:add HUBOT_IRC_PORT=6767

% heroku config:add HUBOT_IRC_USERNAME="..."

% heroku config:add HUBOT_IRC_PASSWORD="..."

% heroku config:add HUBOT_IRC_NICKSERV_PASSWORD="..."

% heroku config:add HUBOT_IRC_SERVER_FAKE_SSL="true"

% heroku config:add HUBOT_IRC_UNFLOOD="true"

% heroku config:add HUBOT_IRC_DEBUG="true"

% heroku config:add HUBOT_IRC_USESSL="true"

% heroku config:add HUBOT_IRC_USESASL="true"

$3

% export HUBOT_IRC_SERVER="..."

% export HUBOT_IRC_ROOMS="#foo,#bar"

Optional

% export HUBOT_IRC_NICK="..."

% export HUBOT_IRC_PORT=6767

% export HUBOT_IRC_USERNAME="..."

% export HUBOT_IRC_PASSWORD="..."

% export HUBOT_IRC_NICKSERV_PASSWORD="..."

% export HUBOT_IRC_SERVER_FAKE_SSL="true"

% export HUBOT_IRC_UNFLOOD="true" # Can optionally be passed a number (in milliseconds) that will be used as the delay between messages

% export HUBOT_IRC_DEBUG="true"

% export HUBOT_IRC_USESSL="true"

% export HUBOT_IRC_USESASL="true"

$3

From Powershell:

setx HUBOT_IRC_SERVER "..." /m

setx HUBOT_IRC_ROOMS "#foo,#bar" /m

$3

gem install foreman
git clone https://github.com/github/hubot.git
cd hubot
# this next line makes a deployable version of the bot for heroku or local deployments
make package
mv hubot/ ../testbot
cd ../testbot
- modify package.json to include the version of hubot-irc to test with either an official release or from your local repo
for an example see this https://gist.github.com/3148311
- modify Procfile, change adapter (-a option) to "irc" and change the name (-n option) of the bot
- make sure you followed the usage section from above to set the environment variables (Non-Heroku section)
foreman start

...and that is it

Contribute

Here's the most direct way to get your work merged into the project.

1. Fork the project
2. Clone down your fork
3. Create a feature branch
4. Hack away and add tests, not necessarily in that order
5. Make sure everything still passes by running tests
6. If necessary, rebase your commits into logical chunks without errors
7. Push the branch up to your fork
8. Send a pull request for your branch

Copyright

Copyright © Hubot Irc Community Contributors. MIT License; see LICENSE for further details.