# 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][funbot], so that the bot can announce the event to IRC.

[funbot]: https://notabug.org/fr33domlover/funbot

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 al 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 config
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.

## Bug and Patches

See [here](https://notabug.org/fr33domlover/funbot#reporting-bugs-and-suggesting-features).