SYNOPSIS

check-acls.pl [--verbose] [--hook=update]      REF OLD_COMMIT NEW_COMMIT
check-acls.pl [--verbose] [--hook=pre-receive]

DESCRIPTION

This script can act as one of two different Git hooks to guarantee that only allowed users can push commits and tags to all or specific branches.

To install it you must copy (or link) it to one of the two hook files under .git/hooks in your Git repository: pre-receive and update. In this way, Git will call it with proper name and arguments. For each hook it acts as follows:

update

This hook is invoked multiple times in the remote repository during git push, once per branch being updated. The script checks every commit being updated for the branch.

pre-receive

This hook is invoked once in the remote repository during git push. The script checks every commit being updated for every branch.

It is configured by the following git options, which can be set via the git config command. Note that you may have options set in any of the system, global, or local scopes. The script will use the most restricted one.

check-acls.userenv

When Git is performing its chores in the server to serve a push request it's usually invoked via the SSH or a web service, which take care of the authentication procedure. These services normally make the autenticated user name available in an environment variable. You may tell this hook which environment variabla it is by setting this option to the variable's name. If not set, the hook will try to get the user's name from the USER environment variable and die if it's not set.

check-acls.groups

You can define user groups in order to make it easier to configure general acls. Use this option to tell where to find group definitions in one of these ways:

file:PATH/TO/FILE

As a text file named by PATH/TO/FILE, which may be absolute or relative to the hooks current directory, which is usually the repository's root in the server. It's sintax is very simple. Blank lines are skipped. The hash (#) character starts a comment that goes to the end of the current line. Group definitions are lines like this:

groupname = userA userB @othergroupname userC

Each group must be defined in a single line. Spaces are significant only between users and group references.

Note that a group can reference other groups by name. To make a group reference, simple prefix its name with an at sign (@). Group references must reference groups previously defined in the file.

GROUPS

If the option's value doesn't start with any of the above prefixes, it must contain the group definitions itself.

check-acls.admin

When this hook is installed, by default no user can change any reference in the repository, unless she has an explicit allowance given by one ACL (se the check-acls.acl option below). It may be usefull to give full access to a group of admins who shouldn't be subject to the ACL specifications. You may use one or more such options to give admin access to a group of people. The value of each option is interpreted in one of these ways:

username

A username specifying a single user. The username specification must match "/^\w+$/i" and will be compared to the authenticated user's name case sensitively.

@groupname

A groupname specifying a single group. The groupname specification must follow the same rules as the username above.

^regex

A regex which will be matched against the authenticated user's name case-insensitively. The caret is part of the regex, meaning that it's anchored at the start of the username.

check-acls.acl

The authorization specification for a repository is defined by the set of ACLs defined by this option. Each ACL specify 'who' has 'what' kind of access to which refs, by means of a string with three components separated by spaces:

who what refname

By default, nobody has access to anything, except the above-specified admins. During an update, all the ACLs matching the authenticated user's name are checked to see if she has authorization to do what she wants to specific branches and tags.

The 'who' component specifies to which users this ACL gives access. It can be specified in the same three ways as was explained to the check-acls.admin option above.

The 'what' component specifies what kind of access to allow. It's specified as a string of one or more of the following opcodes:

C

Create a new ref.

R

Rewind/Rebase an existing ref. (With commit loss.)

U

Update an existing ref. (A fast-forward with no commit loss.)

D

Delete an existing ref.

The 'refname' component specifies which refs this ACL applies to. It can be specified as the complete ref name (e.g. "refs/heads/master") or by a regular expression starting with a caret (^), which is kept as part of the regexp.

REFERENCES

This script is heavily inspired (and sometimes derived) from the update-paranoid example hook which comes with the Git distribution (https://github.com/gitster/git/blob/b12905140a8239ac687450ad43f18b5f0bcfb62e/contrib/hooks/update-paranoid).