master TOC | main page | single-page | license | New: Gitolite Essentials book
This is for gitolite "g3"; for older (v2.x) documentation click here
Gitolite fires off external commands at several different times. The rc file specifies what commands to run at each trigger point, but for illustration, here's an excerpt. Note that as of v3.4, this is not how the rc file looks like externally. Please see this for more.
%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)
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:
...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).
Triggers receive the following arguments:
any arguments mentioned in the rc file (for an example, see the renice command)
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,
followed by zero or more arguments specific to the trigger, as given in the next section.
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
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_1runs after the first access check. Extra arguments:
'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_2runs after the second access check, which is invoked by the update hook to check the ref. Extra arguments:
ACCESS_2 also runs on each 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.
POST_GITrun just before and after the git command. Extra arguments:
NOTE that the
POST_GIT trigger has no way of knowing if the push succeeded, because 'git-shell' (or maybe 'git-receive-pack', I don't know) exits cleanly even if the update hook died.
POST_CREATErun just before and after a new "wild" repo is created by user action. In addition, any command that creates a repo (like 'fork') or potentially changes permissions (like 'perms') may choose to run
POST_CREATE. Extra arguments:
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.
For gitolite v3.3 or less, adding your own scripts to a trigger list was simply a matter of finding the trigger name in the rc file and adding an entry to it. Even for gitolite v3.4 or higher, if your rc file was created before v3.4, it will continue to work, and you can continue to add triggers to it the same way as before.
However, if you installed gitolite v3.4 or higher, you will see a different rc file syntax. This new rc file does not have trigger lists, but a simple list of "features" within a list called "ENABLE" in the rc file; you simply comment out or uncomment appropriate entries, and gitolite will internally create the trigger lists correctly.
...which is fine for triggers that are shipped with gitolite, but now you're wondering how to add your own.
The answer is: same as before.
Here's an example. Let's say you wrote yourself a trigger script called 'foo', to be invoked from the
POST_CREATE trigger list. With the old format, you'd find the following lines in the rc file:
POST_CREATE => [ 'post-compile/update-git-configs', 'post-compile/update-gitweb-access-list', 'post-compile/update-git-daemon-access-list', ],
and you'd simply add a line for 'foo' in that list.
With the new format, since there is no
POST_CREATE trigger list defined in the rc file, you'll need to add all this:
POST_CREATE => [ 'foo' ],
instead of just the 'foo' line.
Since the ENABLE list pulls in the rest of the trigger entries, this will be effectively as if you had done this in a v3.3 rc file:
POST_CREATE => [ 'foo', 'post-compile/update-git-configs', 'post-compile/update-gitweb-access-list', 'post-compile/update-git-daemon-access-list', ],
As you can see, the 'foo' gets added to the top of the list.
You can use the 'gitolite query-rc' command to see what the trigger list actually looks like. For example:
gitolite query-rc POST_CREATE
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.