docs/triggers.mkd

   1 # gitolite triggers
   2
   3 ----
   4
   5 Gitolite runs trigger code at several different times.  The features you
   6 enable in the [rc](rc) file determine what commands to run (or functions in perl
   7 modules to call) at each trigger point.  Example of trigger points are
   8 `INPUT`, `PRE_GIT`, `POST_COMPILE`, etc.; the full list is examined later in
   9 this page.
  10
  11 !!! note ""
  12
  13     Quick tip: triggers are to gitolite what hooks are to git; we simply use a
  14     different name to avoid constantly having to clarify which hooks we mean!
  15     The other difference in gitolite is that each trigger runs multiple pieces
  16     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,
  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     !!! note ""
  88
  89         Note that if access is rejected, gitolite-shell will die as soon as it
  90         returns from the trigger.
  91
  92   * `ACCESS_2` runs after the second access check, which is invoked by the
  93     update hook to check the ref.  Extra arguments:
  94       * repo
  95       * user
  96       * any of W, +, C, D, WM, +M, CM, DM
  97       * the ref being updated (e.g., 'refs/heads/master')
  98       * result
  99       * old SHA
 100       * new SHA
 101
 102     `ACCESS_2` also runs on each [VREF](vref) that gets checked.  In this case
 103     the "ref" argument will start with "VREF/", and the last two arguments
 104     won't be passed.
 105
 106     'result' is similar to `ACCESS_1`, except that it is the *update hook*
 107     which dies as soon as access is rejected for the ref or any of the VREFs.
 108     Control then returns to git, and then to gitolite-shell, so the `POST_GIT`
 109     trigger *will* run.
 110
 111   * `PRE_GIT` and `POST_GIT` run just before and after the git command.
 112     Extra arguments:
 113       * repo
 114       * user
 115       * 'R' or 'W'
 116       * 'any'
 117       * the git command ('git-receive-pack', 'git-upload-pack', or
 118         'git-upload-archive') being invoked.
 119
 120     !!! note ""
 121
 122         Note that the `POST_GIT` trigger has no way of knowing if the push
 123         succeeded, because 'git-shell' (or maybe 'git-receive-pack', I don't
 124         know) exits cleanly even if the update hook died.
 125
 126   * `PRE_CREATE` and `POST_CREATE` run just before and after a new repo is
 127     created.  In addition, any command that creates a repo (like 'fork') or
 128     potentially changes permissions (like 'perms') may choose to run
 129     `POST_CREATE`.
 130
 131     Extra arguments for normal repo creation (i.e., by adding a "repo foo"
 132     line to the conf file):
 133
 134       * repo
 135
 136     Extra arguments for wild repo creation:
 137
 138       * repo
 139       * user
 140       * invoking operation
 141           * 'R' for fetch/clone/ls-remote, 'W' for push
 142           * can also be anything set by the command running the trigger (e.g.,
 143             see the perms and fork commands).  This lets the trigger code know
 144             how it was invoked.
 145
 146   * `POST_COMPILE` runs after an admin push has successfully "compiled" the
 147     config file.  By default, the next thing is to update the ssh authkeys
 148     file, then all the 'git-config's, gitweb access, and daemon access.
 149
 150     No extra arguments.
 151
 152 # adding your own scripts to a trigger
 153
 154 <span class="box-r">Note: for gitolite v3.3 or less, adding your own scripts
 155 to a trigger list was simply a matter of finding the trigger name in the rc
 156 file and adding an entry to it.  Even for gitolite v3.4 or higher, if your rc
 157 file was created before v3.4, *it will continue to work, and you can continue
 158 to add triggers to it the same way as before*.</span>
 159
 160 The rc file (from v3.4 on) does not have trigger lists; it has a simple list
 161 of "features" within a list called "ENABLE" in the rc file.  Simply comment
 162 out or uncomment appropriate entries, and gitolite will *internally* create
 163 the trigger lists correctly.
 164
 165 This is fine for triggers that are shipped with gitolite, but does present a
 166 problem when you want to add your own.
 167
 168 Here's how to do that: Let's say you wrote yourself a trigger script called
 169 'foo', to be invoked from the `POST_CREATE` trigger list.  To do that, just
 170 add the following to the [rc](rc) file, just before the ENABLE section:
 171
 172     POST_CREATE                 =>
 173         [
 174             'foo'
 175         ],
 176
 177 Since the ENABLE list pulls in the rest of the trigger entries, this will be
 178 *effectively* as if you had done this in a v3.3 rc file:
 179
 180     POST_CREATE                 =>
 181         [
 182             'foo',
 183             'post-compile/update-git-configs',
 184             'post-compile/update-gitweb-access-list',
 185             'post-compile/update-git-daemon-access-list',
 186         ],
 187
 188 As you can see, the 'foo' gets added to the top of the list.
 189
 190 ## adding a perl module as a trigger
 191
 192 If your trigger is a perl module, as opposed to a standalone script or
 193 executable, the process is almost the same as above, except what you add to
 194 the rc file it looks like this:
 195
 196     POST_CREATE                 =>
 197         [
 198             'Foo::post_create'
 199         ],
 200
 201 Gitolite will add the `Gitolite::Triggers::` prefix to the name given there.
 202
 203 The subroutine to be run (in this example, `post_create`) is looked for in the
 204 `Gitolite::Triggers::Foo` package, so this requires that the perl module
 205 start with a package header like this:
 206
 207     package Gitolite::Triggers::Foo;
 208
 209 ## displaying the resulting trigger list
 210
 211 You can use the 'gitolite query-rc' command to see what the trigger list
 212 actually looks like.  For example:
 213
 214     gitolite query-rc POST_CREATE
 215
 216 <!--
 217 (ref: https://groups.google.com/forum/#!searchin/gitolite/NON_CORE/gitolite/2kZaqLohSz0/LsIo_W8B2I8J )
 218 -->
 219 <!--
 220
 221 ## running your script AFTER the defaults
 222
 223 By default, your custom scripts will run *before* the shipped ones (e.g., look
 224 at where `foo` landed in the example above).
 225
 226 There is a way to make `foo` land *after* the shipped scripts, but it is not
 227 documented because it never came up till now, and I don't want to commit to it
 228 in case I want to change the implementation.
 229
 230 Let's say your post-compile script is called "my-custom-config". Here's what
 231 you do:
 232
 233 -   add something like 'my-cust' (could be anything you like, as long as it
 234     matches the next step) to the ENABLE list in the rc file. Dont forget the
 235     trailing comma if it's not the last element (and in perl you can add a
 236     trailing comma even if it *is* the last element)
 237
 238 -   after the ENABLE list, but still within the RC hash, add this:
 239
 240         NON_CORE => "
 241         my-cust POST_COMPILE post-compile/my-custom-config
 242         ",
 243
 244     The words in caps are fixed. The others you know, and as you can see the
 245     "my-cust" here matches the "my-cust" in the ENABLE list.
 246
 247 -   After you do this, you can test whether it worked or not:
 248
 249         gitolite query-rc POST_COMPILE
 250
 251     and it should show you what it thinks are the items in that list, in the
 252     order it has them.
 253
 254 -->
 255
 256 # tips and examples
 257
 258 1.  If you have code that latches onto more than one trigger, collecting data
 259     (such as for logging), then the outputs may be intermixed.  You can record
 260     the value of the environment variable `GL_TID` to tie together related
 261     entries.
 262
 263     The documentation on the [log file format][lff] has more on this.
 264
 265 2.  If you look at CpuTime.pm, you'll see that it's `input()` function doesn't
 266     set or change anything, but does set a package variable to record the
 267     start time.  Later, when the same module's `post_git()` function is
 268     invoked, it uses this variable to determine elapsed time.
 269
 270     *(This is a very nice and simple example of how you can implement features
 271     by latching onto multiple events and sharing data to do something)*.
 272
 273 3.  You can even change the reponame the user sees, behind his back.  Alias.pm
 274     handles that.
 275
 276 4.  Finally, as an exercise for the reader, consider how you would create a
 277     brand new env var that contains the *comment* field of the ssh pubkey that
 278     was used to gain access, using the information [here][kfn].
 279
 280 [lff]: dev-notes#appendix-2-log-file-format
 281 [kfn]: sts#distinguishing-one-key-from-another
 282
 283 <!--
 284
 285   - PRE_GIT, ACCESS_1, and ACCESS_2 must only write to STDERR
 286
 287   - perl triggers should not chdir() away
 288
 289 -->
 290