funbot-git-hook

funbot-git-hook

This is a program to use as a Git post-receive hook, which collects new commits and tags made in the Git push, and reports them to a running instance of FunBot, so that the bot can announce the event to IRC.

See below for usage instructions.

The official download location is the Git repository:

https://notabug.org/fr33domlover/funbot-git-hook.git

Occasionally, releases are made to Hackage, the Haskell package repository. See http://hackage.haskell.org/package/funbot-git-hook.

This software is free software, and is committed to software freedom. It is released to the public domain using the CC0 Public Domain Dedication. For the boring "legal" details see the file COPYING.

See the file INSTALL for hints on installation. The file ChangeLog explains how to see the history log of the changes done in the code. NEWS provides a friendly overview of the changes for each release.

Usage Instructions

Quickstart

If you feel you already know the details and just want to get the hook working quickly, here's a usage example you can adapt to your needs. If these quick instructions are all familiar, great! Otherwise, there is a detailed guide in the next section.

The commands below assume manual management of git config and hooks for the server. If you prefer to use Gitolite's features instead, check the Gitolite website or read the hints provided in the next sections.

On the machine where you build the hook program:

$ sudo add-apt-repository ppa:hvr/ghc
$ sudo apt-get update
$ sudo apt-get install cabal-install-1.22 ghc-7.8.4
$ echo 'export PATH=~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.8.4/bin:$PATH' >> ~/.bashrc
$ PATH=~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.8.4/bin:$PATH
$ cabal update
$ cd /home/joe

If you're using git master:

$ git clone https://notabug.org/fr33domlover/funbot-git-hook.git
$ cd funbot-git-hook
$ cabal sandbox init
$ cabal install --only-dependencies
$ cabal build

If you're using the Hackage release:

$ mkdir funbot-sandbox
$ cd funbot-sandbox
$ cabal sandbox init
$ cabal install funbot-git-hook

Now copy dist/build/funbot-client-post-receive/funbot-client-post-receive to the server as /var/lib/gitserver/repos/myrepo.git/hooks/post-receive.

On the git server machine:

# su - git
$ git config --global funbot.commit-url-template 'http://git.rel4tion.org/?p=${repo}.git;a=commitdiff;h=${commit}'
$ cd repos/myrepo.git
$ git config --local funbot.owner johndoe
$ git config --local funbot.bot-url 'http://bot.rel4tion.org/client'

Run ldd funbot-client-post-receive (on the binary) and make sure the listed libraries are installed.

Intro

Some development platforms, such as Gogs and GitLab, have web hook support. FunBot supports the web hook data formats of some of them, and then this package isn't needed. But some platforms are perhaps not supported by FunBot yet. And some are simple git servers which perhaps don't have web hooks at all, for example Gitolite. For these cases, funbot-git-hook provides the ability to report events to a FunBot instance.

I expect that Gitolite will be the primary use case of this package, and the instructions below explain both the general case, and specific hints for Gitolite server admins.

Git Server

Suppose you have a git server with repositories placed under /var/lib/gitserver/repos, and they are bare repos. There is a system user named git whose home directory is /var/lib/gitserver. We'd like to add a git hook to a repo named myrepo, whose path would be /var/lib/gitserver/repos/myrepo.git.

Git Config

The hook program takes its parameters from the git config. It checks both in the global user config and in the repo-specific config.

The following config options are used:

funbot.commit-url-template

When FunBot announces a commit, it specifies a URL meant to refer to a web page showing commit details. For example, if you use Gitolite, you probably use gitweb or cgit to generate a web interface for browsing the repos. This config option allows you to specify a template for that URL. The template contains 3 variables, which will be inserted by the hook program when it runs:

1. repo : the repository name, without a .git suffix
2. branch : name of the branch the commit belongs to
3. commit : commit reference in the form of a SHA hash

Your template doesn't have to include all 3. Use the ones you need.

Variables in the template are specified like $var or like ${var}. Use $$ to get a literal $ character. For example, this works with gitweb:

http://git.rel4tion.org/?p=${repo}.git;a=commitdiff;h=${commit}

This config option is optional. If you don't specify it, an empty URL will be assumed. You'll probably want to specify it in the global config (~/.gitconfig), since on a single git server instance your repos most likely share the same template.

# su - git
$ git config --global funbot.commit-url-template 'http://git.rel4tion.org/?p=${repo}.git;a=commitdiff;h=${commit}'

If you use Gitolite, you can set it globally for all the repos in your gitolite.conf like this:

repo @all
    config funbot.commit-url-template = "http://git.rel4tion.org/?p=${repo}.git;a=commitdiff;h=${commit}"

Note that by default Gitolite will refuse to accept this config line because the value contains a character considered unsafe, $. See the Gitolite website for more info and instructions how to safely allow $ to be used.

funbot.owner

FunBot maintains a list of repositories, and configuration for announcing their events. For example, to which IRC channel should your repo's commits be announced? For which branches? What to do if a large amount of commits are pushed at once? FunBot keeps this information. When a commit is reported to it, it needs to go to these records, find your repo's name and fetch the configurations for it. But since different people and servers may have repos with identical name, FunBot uses two things to identify and find a repo in its records:

1. The repo name
2. A repo owner string, i.e. a username of a person responsible for the repo

This config option allows you to specify the owner string. It is required. If no owner string is found, nothing will be sent to FunBot. Assuming you set this per-repo, you can do it like this on the command line:

# su - git
$ cd ~/repos/myrepo.git
$ git config --local funbot.owner johndoe

Or using Gitolite:

repo myrepo
    RW+ = johndoe
    R   = daemon
    config funbot.owner = johndoe

The first johndoe is matched by Gitolite against the SSH key filenames, while the second johndoe is an arbitrary owner nickname you can pick. They don't have to be identical, but it may be a good idea to keep them identical for consistency, and for cases your web UI contains author links etc.

funbot.bot-url

FunBot accept events from clients through an HTTP based API. This config option is the URL at which your favorite FunBot instance accepts events. It is required.

For example, http://bot.rel4tion.org/client.

Deploying the Hook Program

There are several ways to deply the hook:

• Build it somewhere else and copy the binary to the server
• Install it on the server
• Build it in a sandbox on the server
• Run it as a script using the Haskell interpreter

Technically there could also be "use a distro package" but there is none yet. Contributions are very welcome, especially for making a deb package for Trisquel.

If you're not sure which one to pick, I suggest the first option. Build from the safety and comfort of your personal computer, and just copy the binary. That binary does require some dependency libraries to be present, but most of them are commonly available and you can use the ldd command on it to determine exactly which dependencies are needed.

The binary executable contains its Haskell library dependencies, so it's bigger than a typical git hook, which is often a simple script. On my system, its size is 19MB. You can try to make it smaller by stripping symbols, if you want.

Building and Deploying the Binary

I'll assume the distribution used is Trisquel GNU/Linux-libre. The same commands should probably work for other Debian-based distributions. Adapt to your system as needed.

Add a PPA and install a basic Haskell tools (compiler, package manager, etc.):

$ sudo add-apt-repository ppa:hvr/ghc
$ sudo apt-get update
$ sudo apt-get install cabal-install-1.22 ghc-7.8.4

Add ~/.cabal/bin:/opt/cabal/1.22/bin:/opt/ghc/7.8.4/bin to your $PATH in bashrc or similar.

Download the package index:

$ cabal update

If you'd like to use the package release from Hackage, install it inside a fresh sandbox:

$ mkdir funbot-sandbox
$ cd funbot-sandbox
$ cabal sandbox init
$ cabal install funbot-git-hook

If you're instead working with a git clone, go to the repo directory and create a cabal sandbox:

$ cd /home/joe/git-repos/funbot-git-hook
$ cabal sandbox init

Install dependency packages:

$ cabal install --only-dependencies

Build the program:

$ cabal build

Now dist/build/funbot-client-post-receive/ contains a binary executable funbot-client-post-receive. Use ldd to determine which libraries it links to at runtime and make sure they are installed on the server (hopefully most if not all of them will be available as distro packages).

Finally, you can put the binary on the server as /var/lib/gitserver/repos/myrepo.git/hooks/post-receive. If you use Gitolite, you can instead drop it in the /var/lib/gitserver/local/hooks/repo-specific directory, and specify it in gitolite.conf:

repo myrepo
    RW+ = johndoe
    R   = daemon
    config funbot.owner = johndoe
    option hook.post-receive = funbot-client-post-receive

Running using the Interpreter

If you want to do that for any reason, here's how. Install the packages from the PPA on the server. Do the rest as the git user. Clone this repo if you haven't yet. Instead of creating a sandbox, run a single cabal install --only-dependencies which will install the dependencies locally for the git user.

Now add #!/usr/bin/env runhaskell as the first line of src/Main.hs, make this file executable (chmod +x src/Main.hs) and copy it to the final location as explained for the binary at the bottom of the previous section.

Bugs and Patches

See here.