triggers.mkd

   1 <!-- options: toc -->
   2
   3 % gitolite triggers
   4
   5 include sidebar-toc
   6
   7 Gitolite runs trigger code at several different times.  The features you
   8 enable in the [rc][] file determine what commands to run (or functions in perl
   9 modules to call) at each trigger point.  Example of trigger points are
  10 "INPUT", "PRE\_GIT", "POST\_COMPILE", etc.; the full list is examined later in
  11 this page.
  12
  13 @@gray(Quick tip: triggers are to gitolite what hooks are to git; we simply
  14 use a different name to avoid constantly having to clarify which hooks we
  15 mean!  The other difference in gitolite is that each trigger runs multiple
  16 pieces of code, not just one program with the same name as the hook, like git
  17 does.))@@
  18
  19 # types of trigger programs
  20
  21 There are two types of trigger programs.  Standalone scripts are placed in
  22 triggers or its subdirectories.  Such scripts are quick and easy to write in
  23 any language of your choice.
  24
  25 Triggers written as perl modules are placed in lib/Gitolite/Triggers.  Perl
  26 modules have to follow some conventions (see some of the shipped modules for
  27 ideas) but the advantage is that they can set environment variables and change
  28 the argument list of the gitolite-shell program that invokes them.
  29
  30 If you intend to write your own triggers, it's a good idea to examine a
  31 default install of gitolite, paying attention to:
  32
  33   * the path names in various trigger lists in the rc file,
  34   * corresponding path names in the src/ directory in gitolite source, and
  35   * and for perl modules, the package names and function names within.
  36
  37 # manually firing triggers
  38
  39 It's easy to manually fire triggers from the server command line.  For
  40 example:
  41
  42     gitolite trigger POST_COMPILE
  43
  44 However if the triggered code depends on arguments (see next section) this
  45 won't work.  (The `POST_COMPILE` trigger programs all just happen to not
  46 require any arguments, so it works).
  47
  48 # common arguments
  49
  50 Triggers receive the following arguments:
  51
  52 1.  Any arguments mentioned in the rc file (for an example, see the renice
  53     command).
  54
  55 2.  The name of the trigger as a string (example, `"POST_COMPILE"`), so you
  56     can call the same program from multiple triggers and it can know where it
  57     was called from.
  58
  59 3.  And finally, zero or more arguments specific to the trigger, as given in
  60     the next section.
  61
  62 # trigger-specific arguments and other details
  63
  64 Here are the **rest of** the arguments for each trigger, plus a brief
  65 description of when the trigger runs.  (Note that when the repo name is passed
  66 in as an argument, it is without the '.git' suffix).
  67
  68   * `INPUT` runs before pretty much anything else.  INPUT trigger scripts
  69     *must* be in perl, since they manipulate the arguments and the environment
  70     of the 'gitolite-shell' program itself.  Most commonly they will
  71     read/change `@ARGV`, and/or `$ENV{SSH_ORIGINAL_COMMAND}`.
  72
  73     There are certain conventions to adhere to; please see some of the shipped
  74     samples or ask me if you need help writing your own.
  75
  76   * `ACCESS_1` runs after the first access check.  Extra arguments:
  77       * repo
  78       * user
  79       * 'R' or 'W'
  80       * 'any'
  81       * result (see notes below)
  82
  83     'result' is the return value of the access() function.  If it contains the
  84     uppercase word "DENIED", the access was rejected.  Otherwise it is the
  85     refex that caused the access to succeed.
  86
  87     *Please note that if access is rejected, gitolite-shell will die as soon
  88     as it returns from the trigger*.
  89
  90   * `ACCESS_2` runs after the second access check, which is invoked by the
  91     update hook to check the ref.  Extra arguments:
  92       * repo
  93       * user
  94       * any of W, +, C, D, WM, +M, CM, DM
  95       * the ref being updated (e.g., 'refs/heads/master')
  96       * result
  97       * old SHA
  98       * new SHA
  99
 100     `ACCESS_2` also runs on each [VREF][vref] that gets checked.  In this case
 101     the "ref" argument will start with "VREF/", and the last two arguments
 102     won't be passed.
 103
 104     'result' is similar to `ACCESS_1`, except that it is the *update hook*
 105     which dies as soon as access is rejected for the ref or any of the VREFs.
 106     Control then returns to git, and then to gitolite-shell, so the `POST_GIT`
 107     trigger *will* run.
 108
 109   * `PRE_GIT` and `POST_GIT` run just before and after the git command.
 110     Extra arguments:
 111       * repo
 112       * user
 113       * 'R' or 'W'
 114       * 'any'
 115       * the git command ('git-receive-pack', 'git-upload-pack', or
 116         'git-upload-archive') being invoked.
 117
 118     **NOTE** that the `POST_GIT` trigger has no way of knowing if the push
 119     succeeded, because 'git-shell' (or maybe 'git-receive-pack', I don't know)
 120     exits cleanly even if the update hook died.
 121
 122   * `PRE_CREATE` and `POST_CREATE` run just before and after a new repo is
 123     created.  In addition, any command that creates a repo (like 'fork') or
 124     potentially changes permissions (like 'perms') may choose to run
 125     `POST_CREATE`.
 126
 127     Extra arguments for normal repo creation (i.e., by adding a "repo foo"
 128     line to the conf file):
 129       * repo
 130
 131     Extra arguments for wild repo creation:
 132       * repo
 133       * user
 134       * invoking operation
 135           * 'R' for fetch/clone/ls-remote, 'W' for push
 136           * can also be anything set by the command running the trigger (e.g.,
 137             see the perms and fork commands).  This lets the trigger code know
 138             how it was invoked.
 139
 140   * `POST_COMPILE` runs after an admin push has successfully "compiled" the
 141     config file.  By default, the next thing is to update the ssh authkeys
 142     file, then all the 'git-config's, gitweb access, and daemon access.
 143
 144     No extra arguments.
 145
 146 # adding your own scripts to a trigger {#addtrig}
 147
 148 @@box-r(Note: for gitolite v3.3 or less, adding your own scripts to a trigger
 149 list was simply a matter of finding the trigger name in the rc file and adding
 150 an entry to it.  Even for gitolite v3.4 or higher, if your rc file was created
 151 before v3.4, *it will continue to work, and you can continue to add triggers
 152 to it the same way as before*.)@@
 153
 154 The rc file (from v3.4 on) does not have trigger lists; it has a simple list
 155 of "features" within a list called "ENABLE" in the rc file.  Simply comment
 156 out or uncomment appropriate entries, and gitolite will *internally* create
 157 the trigger lists correctly.
 158
 159 This is fine for triggers that are shipped with gitolite, but does present a
 160 problem when you want to add your own.
 161
 162 Here's how to do that: Let's say you wrote yourself a trigger script called
 163 'foo', to be invoked from the `POST_CREATE` trigger list.  To do that, just
 164 add the following to the [rc][] file, just before the ENABLE section:
 165
 166     POST_CREATE                 =>
 167         [
 168             'foo'
 169         ],
 170
 171 Since the ENABLE list pulls in the rest of the trigger entries, this will be
 172 *effectively* as if you had done this in a v3.3 rc file:
 173
 174     POST_CREATE                 =>
 175         [
 176             'foo',
 177             'post-compile/update-git-configs',
 178             'post-compile/update-gitweb-access-list',
 179             'post-compile/update-git-daemon-access-list',
 180         ],
 181
 182 As you can see, the 'foo' gets added to the top of the list.
 183
 184 ## displaying the resulting trigger list
 185
 186 You can use the 'gitolite query-rc' command to see what the trigger list
 187 actually looks like.  For example:
 188
 189     gitolite query-rc POST_CREATE
 190
 191 # tips and examples
 192
 193 1.  If you have code that latches onto more than one trigger, collecting data
 194     (such as for logging), then the outputs may be intermixed.  You can record
 195     the value of the environment variable `GL_TID` to tie together related
 196     entries.
 197
 198     The documentation on the [log file format][lff] has more on this.
 199
 200 2.  If you look at CpuTime.pm, you'll see that it's `input()` function doesn't
 201     set or change anything, but does set a package variable to record the
 202     start time.  Later, when the same module's `post_git()` function is
 203     invoked, it uses this variable to determine elapsed time.
 204
 205     *(This is a very nice and simple example of how you can implement features
 206     by latching onto multiple events and sharing data to do something)*.
 207
 208 3.  You can even change the reponame the user sees, behind his back.  Alias.pm
 209     handles that.
 210
 211 4.  Finally, as an exercise for the reader, consider how you would create a
 212     brand new env var that contains the *comment* field of the ssh pubkey that
 213     was used to gain access, using the information [here][kfn].