irker and irkerhook.py are intended to be installed on forge sites such as SourceForge, GitHub, GitLab, 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 a 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. The short version: as long as your firewall blocks port 6659 and irkerd is running inside it, you should be fine.
You will need either
Python at version 2.6 or later, which has JSON built in
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.
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 firewall should block port 6659.
The design of irker assumes the machine on which it is running is also inside the firewall, so that repository hooks can reach port 6659.
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.
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
SourceForge is a special case: see
for tools and instructions on how to work around its limitations.
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
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:
There’s also a poller daemon that can watch activity in a Subversion repository and ship notifications via an irker instance.