irker and irkerhook.py are intended to be installed on forge sites such as SourceForge, GitHub, Gitorious, Gna, and Savannah. This file explains the theory of operation, how to install the code, and how to test it.

Theory of operation

irkerhook.py creates JSON notification requests and ships them to irkerd’s listener socket. irkerd run as a daemon in order to maintain all the client state required to post multiple notifications while generating minimum of join/leave messages (which, from the point of view of humans watching irkerd’s output, are mere spam).

See the security.txt document for a detailed discussion of security and DoS vulnerabilities related to irker.

Prerequisites

You will need either

  1. Python at version 2.6 or later, which has JSON built in

  2. Python at version no older than 2.4, and a version of the simplejson library installed that it can use. Some newer versions of simplejson discard 2.4 compatibility; 2.0.9 is known to work.

Installing irkerd

irker needs to run constantly, watching for TCP and UDP traffic on port 6659. Install it accordingly. It has no config file; you can just start it up with no arguments. If you want to see what it’s doing, give it command-line options -d 1 for sparse messages and -d 2 to show all traffic with IRC servers.

You should not make irker visible from outside the site firewall, as it can be used to spam IRC channels while masking the source address.

The file org.catb.irkerd.plist is a Mac OS/X plist that can be installed to launch irkerd as a boot-time service on that system.

Installing irkerhook.py

Under git, a call to irkerhook.py should be installed in the update hook script of your repo. Under Subversion, the call goes in your repo’s post-commit script. Under Mercurial there are two different ways to install it. See the irkerhook manual page for details; the source is irkerhook.xml in this distribution.

Note that if you were using the CIA service and have ciabot.py in your git update script, you can simply replace this

with this:

SourceForge is a special case: see

for tools and instructions on how to work around its limitations.

Testing

To verify that your repo produces well-formed JSON notifications, you can run irkerhook.py in the repo directory using the -n switch, which emits JSON to standard output rather than attempting to ship to an irkerd instance.

Then, start irkerd and call irkerhook.py while watching the freenode #commits channel.

The irk script is a little test tool that takes two arguments, a channel and a message, and does what you’d expect.

If you need help, there’s a project chat channel at

irc://chat.freenode.net/#irker

Read-only access

If, for whatever reason, you can’t modify the hook scripts in your repository, there is still hope.

There’s a proxy that takes CIA XML-RPC notifications and passes them to a local irker instance. Find it here:

https://github.com/nenolod/irker-cia-proxy

There’s also a poller daemon that can watch activity in a Subversion repository and ship notifications via an irker instance.

https://github.com/shikadilord/irker-svnpoller