KGB for your alioth project

This short document describes how to set up the hooks in your version control system provided by alioth.debian.org in order to relay commits to a set of KGB bots that serve alioth projects. If you are looking for using your own bots, or if your project is not hosted on alioth, see Don's tutorial.

Configuration

KGB receives its options from the command line parameters or a configuration file. Using a configuration file is often better, because the same file can be used by multiple sub-projects.

Here's sample configuration, suitable for alioth-based projects that want to use the provided bots:

---
repo-id: PROJECT-ID
# see below about generating a password and mailing it
password: "truly secret"
servers:
   # KGB-0, run by dmn@debian.org
 - uri: http://kgb.ktnx.org:9418/
   # KGB-1, run by tincho@debian.org
 - uri: http://kgb.tincho.org:9418/
   # KGB-2, run by gregoa@debian.org
 - uri: http://colleen.colgarra.priv.at:8080/

branch-and-module-re:
 - "/(trunk|tags|apps|attic)/([^/]+)"
 - "/branches/([^/]+)/([^/]+)"
web-link: "http://anonscm.debian.org/viewvc/${module}/${branch}/?commit=${commit}"
use-irc-notices: 0
use-color: 1

See kgb-client.conf manual for more information about the different options.

The three servers also need to be configured before they can recognize your project. Please mail your prefered project ID (usually the same as the alioth project name), password (see pwgen(1)) and IRC channel to {dmn,gregoa,tincho}@debian.org.

In order to simplify the servers setting in the configuration, we plan to either make kgb-client able to include files so that we can provide an authoritative list of servers that can be changed without requiring changes in all projects, or make it work properly with DNS round-robin records and provide a single kgb.debian.net name pointing to available servers.

VCS Hooks

Since KGB development is hosted on alioth, there is a ready to be used client available to all other projects. It is at /home/groups/kgb/trunk.

Note that all committers need read access to the kgb-client.conf file. In case your alioth project is set up to allow commits from all Debian developers, this may be a problem for those of them that aren't members of the alioth project. The problem shows up as warnings on commit:

Warning: post-commit hook failed (exit code 2) with output:
YAML Error: Couldn't open /home/groups/my-project/kgb-client.conf for input:\nNo such file or directory
   Code: YAML_LOAD_ERR_FILE_INPUT
 at /usr/share/perl5/YAML.pm line 71

The remedy is to give read access to all Debian developers to the configuration file:

setfacl -m g:Debian:r /home/groups/my-project/kgb-client.conf

Git

Put the following in hooks/post-receive:

exec /home/groups/kgb/bin/kgb-client-trunk

and make sure to configure it with:

git config kgb.conf /home/groups/my-project/kgb-client.conf

In case there are other hooks that need to be run, the standard input needs to be duplicated, as in:

exec pee /home/groups/kgb/bin/kgb-client-trunk /usr/local/bin/git-commit-notice

Subversion

Here's sample content of the hooks/post-commit file.

REPOS="$1"
REV="$2"

# KGB notifications
KGB_CLIENT=/home/groups/kgb/bin/kgb-client-trunk
GRP_HOME=/home/groups/my-project
$KGB_CLIENT --conf $GRP_HOME/kgb-client.conf "$REPOS" "$REV"

CVS

kgb-client shall be installed in the loginfo file in the CVSROOT module of the CVS repository. It shall be given two arguments -- the repository root, and the directory in which the changes are being made.

ALL /home/groups/kgb/bin/kgb-client-trunk --conf /home/groups/my-project/kgb-client.conf "$CVSROOT" "%p"