gitaclhook − control access to git repositories
gitaclhook refname old−sha1 new−sha1
gitacthook [−−debug] −−test REPO USER OP REF
This program is intended to be run as an "update" hook by git. It is called by git-receive-pack with arguments: refname old−sha1 new−sha1.
The program reads access control lists from the storage engine specified in the repository’s config file and allows or denies the update depending on their settings. If no storage engine is defined update is allowed unconditionally. If it is defined, but is not available (e.g. the disk file does not exist or the LDAP server cannot be reached, the update is denied.
Two storage engines are supported: File, which reads access control lists from a disk file, and LDAP , which obtains them from LDAP . The engine to use is defined by the hooks.acltype configuration keyword. The default is File.
The ACL file is used when the File storage engine is requested. The path to the file must be given via the hooks.aclfile configuration keyword. If hooks.aclfile is not defined, update is allowed unconditionally.
The ACL file has the usual line-oriented syntax. Comments are introduced by the # sign and extend to the end of the physical line. Comments and empty lines are ignored.
Non-empty lines introduce ACL rules. The syntax is:
VERB PROJECT USER [ OP REF ]
denote optional parts. The parts of an ACL
Either allow or deny, to allow or deny the operation, correspondingly.
The name of the project. It is obtained by removing the directory and suffix parts of the repository pathname. Thus, if the repository is located in /var/gitroot/foobar.git, then the corresponding name of the project is foobar.
An asterisk matches any project name.
Name of the user. The word all stands for any user, the word none matches no one at all. Otherwise, if this part begins with a percent sign (%), the rest of characters are treated as the name of the UNIX group to check and the rule matches any user in that group. Otherwise, the literal match is assumed.
The optional parts are:
Requested operation codes. It is a string consisting of one or more of the following letters (case-insensitive):
Create new ref.
Delete existing ref.
Fast-forward existing ref (no commit loss).
Rewind or rebase existing ref (commit loss).
Affected ref, relative to the git refs/ directory. If it begins with a caret (^), it is treated as a Perl regular expression (with the ^ being its part). If it ends with a /, it is treated as a prefix match, so, e.g., heads/baz/ matches refs/heads/baz and anything below. Otherwise, it must match exactly the affected ref.
The rule applies only if its PROJECT and USER parts match the project which is being updated and the user who requests the update, its OP contains the opcode of the requested operation and REF matches the affected ref. Missing REF and/or OP are treated as a match.
If no rule applies, the operation is allowed.
For example, assume you have the following ACL file:
allow myprog %devel U heads/master allow myprog %pm CDUR heads/ allow myprog %pm C ^heads/tags/v\\d+$ allow myprog admin CDUR deny myprog all
Then the users from the devel group will be able to push updates to refs/heads/master, the users from the pm group will be allowed to do anything with refs under refs/heads and to create tags with names beginning with v and containing only digits afterwards, and the user admin will be allowed to do anything he pleases. No other users will be allowed to update that repository.
The LDAP storage engine is requested by the following configuration statement:
[hooks] acltype = LDAP
URI of the LDAP server to use
and other data necessary to access it are read from the file
name given in the hooks.aclldapconf variable, or from
/etc/ldap.conf, if it is not defined.
LDAP access control entries are similar to
the plaintext file ACLs. Each entry has the following
The project this entry applies to.
The control verb.
The user name or group (% GROUPNAME ) specification.
The list of operation codes.
Sorting order (see below).
The program first reads all entries with the gitAclProject attribute matching the requested project name. The obtained entries are sorted by the value of gitAclOrder attribute. Entries without this attributes are assumed to have sorting order 0. Entries with the project name all are sorted last. Entries with the same sorting order are sorted by the count of attributes they carry (in the reverse order). Thus, the most specific entries precede the least specific entries in the resulting list.
Each list entry is then matched against the current tuple ( PROJECT , USER , OP , REF ), much the same way as described in RULE MATCHING . Missing attributes always match. The special gitAclProject value all matches all project names.
If no matching entry is found, the update is allowed.
Type of the storage engine. Valid values are File (default) and LDAP .
For the File storage engine, name of the ACL file.
For the LDAP storage engine, the name of the configuration file to use instead of /etc/ldap.conf.
Send log info to this file.
Enable debugging. The bigger the number, the more debugging info will be displayed.
Suppress diagnostics on stderr.
Name of the user httpd runs as. Define it if the repository can be accessed via HTTP (S). If gitaclhook is run as this user, it will get the name of the user on behalf of which the update is performed from the environment variable REMOTE_USER .
The −−test (−t) option provides a mechanism for testing access control lists from the command line. The syntax is:
gitacthook [−−debug] [−d] −−test REPO USER OP REF
REPO is a pathname of the repository to test, USER is the username, OP is the operation code and REF is the reference.
Optional −−debug (−d) options increment the debugging level.
uses following environment variables:
When set to 1, enables debugging mode. The hooks.acldebug configuration variable overrides this setting.
Path to the affected repository.
If updates are
performed via HTTP or HTTPS
and the hooks.httpd−user configuration variable
is set, the following two variables are used to determine
the identity of the user:
If this variable is not set or set to an empty value, the program will deny the update.
The authenticated name of the user.
Sergey Poznyakoff, <firstname.lastname@example.org>
Manpage server at Ulysses.gnu.org.ua.
Powered by mansrv 1.0