Skip to content

Tutorial for Git administrators

Jump to bottom
Gustavo Chaves edited this page Jun 16, 2017 · 2 revisions

Introduction

As the administrator of a Git server you may be interested in enabling some hooks for your Git repositories to enforce project policies through source code verification or access rights.

Server Driver Script

The same driver script described above for user repositories can be used for server repositories:

#!/usr/bin/env perl
use Git::Hooks;
run_hook($0, @ARGV);

As a Git administrator, I save it as /usr/local/bin/githooks.pl in my Git server. You may save it elsewhere in the machine your hooks will run. Just do not forget to make it executable!

Server Hook Links

As a Git administrator, you would be interested in the back-end hooks. So, you should create some symbolic links under the .git/hooks directories of your repositories pointing to the drive script:

$ cd .../.git/hooks
$ ln -s /usr/local/bin/githooks.pl pre-receive
$ ln -s /usr/local/bin/githooks.pl update
$ ln -s /usr/local/bin/githooks.pl ref-update

Also, read the section about "Automating the creation of links" to know to have such links automatically created for you when you initialize or clone a repository.

Server Configuration

In your Git server you should insert global configuration in the $HOME/.gitconfig file at the HOME of the user running Git. This is an example using some of the available plugins:

[githooks]
        plugin = CheckCommit
        plugin = CheckJira
        plugin = CheckLog
        admin = gustavo
[githooks "checkcommit"]
        email-valid = 1
[githooks "checkjira"]
        jiraurl  = https://jira.cpqd.com.br
        jirauser = gustavo
        jirapass = a-very-large-and-difficult-to-crack-password
        matchlog = (?s)^\\[([^]]+)\\]
[githooks "checklog"]
        title-max-width = 62

In the server the CheckCommit, CheckJira, and CheckLog plugins are enabled for every repository. The <githooks.checkjira> section specifies the URL and credentials of the JIRA server as well as where in the commit message the JIRA references are to be looked for.

The githooks.checkcommit enables the email-valid check to guarantee that authors and committers use sane email addresses in their commits.

The githooks.checklog section specifies a nonstandard value for the title-max-width option.

As the administrator, I've configured myself (githooks.admin = gustavo) to be exempt from any checks so that I can brag about my superpowers to my fellow users. Seriously, though, sometimes it's necessary to be able to bypass some checks and this is a way to allow some user to do it.

In particular repositories you can make local configurations to complement or supersede the global configuration. This is an example .git/config file:

[githooks]
        disable = CheckJira
        plugin = CheckAcls
        groups = integrators = tiago juliana
[githooks "checkacls"]
        acl = @integrators CRUD ^refs/(heads|tags)/
        acl = ^.           CRUD ^refs/heads/user/{USER}/'
        acl = ^.           U    ^refs/heads

In this repository the CheckJira plugin is disabled, even though it is enabled globally.

The CheckAcls plugin is enabled and configured in the githooks.checkacls section with three ACLs.

The first ACL allows the two users belonging to the integrators group to create, rewrite, update, and delete any branch or tag.

The second ACL allows any user to create, rewrite, update, and delete any branch with a name beginning with user/USER, where USER is the username with which she authenticated herself with Git. This is useful to allow developers to backup their own local branches in the server while they aren't good enough to be shared.

The third ACL allows any user to update any branch, which means, to push to any branch and have it be fast-forwarded.

Distributed configuration

By default you only get a single global and one local configuration file for each repository in the server. Sometimes it's useful to factor out some configuration in specific files. If you have, say, three development teams holding their repositories in a single server but each one of them wants different CheckAcls configuration you may separate these configurations in three files and include one of them in each repository using Git's include section. For example, team A's repositories could have this in their .git/config files:

[include]
        path = /usr/local/etc/githooks/teamA.acls

Using include files you can manage complex configurations more easily.

Clone this wiki locally