gitolite/doc/triggers.mkd

# gitolite triggers

[[TOC]]

## intro and sample rc excerpt

Gitolite fires off external commands at 7 different times.  The [rc][] file
specifies what commands to run at each trigger point, but for illustration,
here's an excerpt:

    %RC = (

        <...several lines later...>

        # comment out or uncomment as needed
        # these will run in sequence after post-update
        POST_COMPILE                =>
            [
                'post-compile/ssh-authkeys',
                'post-compile/update-git-configs',
                'post-compile/update-gitweb-access-list',
                'post-compile/update-git-daemon-access-list',
            ],

        # comment out or uncomment as needed
        # these will run in sequence after a new wild repo is created
        POST_CREATE                 =>
            [
                'post-compile/update-git-configs',
                'post-compile/update-gitweb-access-list',
                'post-compile/update-git-daemon-access-list',
            ],

(As you can see, post-create runs 3 programs that also run from post-compile.
This is perfectly fine, by the way)

## types of trigger programs

There are two types of trigger programs.  Standalone scripts are placed in
src/triggers or its subdirectories.  They are invoked by being added to a
trigger list (using the path after "src/triggers/", as you can see).  Such
scripts are quick and easy to write in any language of your choice.

Triggers written as perl modules are placed in src/lib/Gitolite/Triggers.
They are invoked by being listed with the package+function name, although even
here the 'Gitolite::Triggers' part is skipped.  Perl modules have to follow
some conventions (see some of the shipped modules to ideas) but the advantage
is that they can set environment variables and change the argument list of the
gitolite-shell program that invokes them.

If this does not make sense, please examine a default install of gitolite,
paying attention to:

  * the path names in various trigger lists in the rc file
  * corresponding path names in the src/ directory in gitolite source
  * and for perl modules, the package names and function names within.

## manually firing triggers

...from the server command line is easy.  For example:

    gitolite trigger POST_COMPILE

However if the triggered code depends on arguments (see next section) this
won't work.  (The `POST_COMPILE` trigger programs all just happen to not
require any arguments, so it works).

## common arguments

Triggers receive the following arguments:

1.  any arguments mentioned in the rc file (for an example, see the renice
    command in the PRE_GIT trigger sequence),

2.  the name of the trigger as a string (example, `"POST_COMPILE"`), so you
    can call the same program from multiple triggers and it can know where it
    was called from,

3.  followed by zero or more arguments specific to the trigger, as given in
    the next section.

## trigger-specific arguments and other details

Here are the **rest of** the arguments for each trigger, plus a brief
description of when the trigger runs:

  * `INPUT` runs before pretty much anything else.  INPUT trigger scripts
    *must* be in perl, since they manipulate the arguments to and the
    environment of the 'gitolite-shell' program itself.  Most commonly they
    will read/change `@ARGV`, and/or `$ENV{SSH_ORIGINAL_COMMAND}`.

    There are certain conventions to adhere to; please see some of the shipped
    samples or ask me if you need help writing your own.

  * `ACCESS_1` runs after the first access check.  Extra arguments:
      * repo
      * user
      * 'R' or 'W'
      * 'any'
      * result (see notes below)

    'result' is the return value of the access() function.  If it contains the
    uppercase word "DENIED", the access was rejected.  Otherwise it is the
    refex that caused the access to succeed.

    *Please note that if access is rejected, gitolite-shell will die as soon
    as it returns from the trigger*.

  * `ACCESS_2` runs after the second access check, which is invoked by the
    update hook to check the ref.  Extra arguments:
      * repo
      * user
      * any of W, +, C, D, WM, +M, CM, DM
      * the ref being updated (e.g., 'refs/heads/master')
      * result
      * old SHA
      * new SHA

    `ACCESS_2` also runs on each [VREF][vref] that gets checked.  In this case
    the "ref" argument will start with "VREF/", and the last two arguments
    won't be passed.

    'result' is similar to `ACCESS_1`, except that it is the *update hook*
    which dies as soon as access is rejected for the ref or any of the VREFs.
    Control then returns to git, and then to gitolite-shell, so the `POST_GIT`
    trigger *will* run.

  * `PRE_GIT` and `POST_GIT` run just before and after the git command.
    Extra arguments:
      * repo
      * user
      * 'R' or 'W'
      * 'any'
      * the git command ('git-receive-pack', 'git-upload-pack', or
        'git-upload-archive') being invoked.

  * `PRE_CREATE` and `POST_CREATE` run just before and after a new "[wild][]"
    repo is created by user action.  Extra arguments:
      * repo
      * user
      * invoking operation
          * 'R' for fetch/clone/ls-remote, 'W' for push
          * can also be anything set by the external command running the
            trigger (e.g., see the perms and fork commands).

    They are also run when a *normal* repo is created (say by adding a "repo
    foo" line to the conf file).  This case has only one extra argument:
      * repo

  * `POST_COMPILE` runs after an admin push has successfully "compiled" the
    config file.  By default, the next thing is to update the ssh authkeys
    file, then all the 'git-config's, gitweb access, and daemon access.

    No extra arguments.

## tips

If you have code that latches onto more than one trigger, collecting data
(such as for logging), then the outputs may be intermixed.  You can record the
value of the environment variable `GL_TID` to tie together related entries.