133 lines
4.8 KiB
Markdown
133 lines
4.8 KiB
Markdown
# gitolite triggers
|
|
|
|
## 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: this is the result of the access() function. If it contains
|
|
the uppercase word "DENIED", the access was rejected. Otherwise
|
|
result contains the refex that caused the access to succeed.
|
|
|
|
* `ACCESS_2` runs after the second access check, in the update hook.
|
|
Extra arguments:
|
|
* repo
|
|
* user
|
|
* any of W, +, C, D, WM, +M, CM, DM
|
|
* the ref being updated (e.g., 'refs/heads/master')
|
|
* result (see above)
|
|
|
|
* `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
|
|
|
|
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.
|