delegating access control responsibilities

Delegation allows you to divide up a large conf file into smaller groups of repos (called subconfs) and hand over responsibility to manage them to sub-admins. Gitolite can prevent one sub-admin from being able to set access rules for any other sub-admin's repos.

Delegation is achieved by combining two gitolite features: subconf and the NAME VREF.


Here's a sample conf that does delegation:

@webbrowsers        = firefox lynx browsers/..*
@webservers         = apache nginx servers/..*
@malwares           = conficker storm ms/..*
    # side note: if anyone objects, we claim ms stands for "metasploit" ;-)

# the admin repo access probably had these 2 lines to start with:
repo gitolite-admin
    RW+                                     = sitaram
# now add these lines to the config for the admin repo
    RW                                      = alice bob mallory
    RW  VREF/NAME/conf/subs/webbrowsers     = alice
    RW  VREF/NAME/conf/subs/webservers      = bob
    RW  VREF/NAME/conf/subs/malwares        = mallory
    -   VREF/NAME/                          = alice bob mallory

# pull in these files using the "subconf" command
subconf "subs/*.conf"

If you've read the VREF part, or at least understood how NAME VREFs work, it should be clear that, in terms of changes to the gitolite-admin repo:

  • The user sitaram has no restrictions of any kind
  • Users alice, bob, and mallory can only touch files within their assigned areas within conf/subs. If they try to change any other file (keydir, conf/gitolite.conf, or something in one of the other sub-admin's areas), then the last rule kicks in and the push gets rejected.

Now all we need is to see what this "subconf" thing is all about.

the subconf command

Subconf is exactly like the include command in syntax:

subconf "foo.conf"

but while reading the included file (as well as anything included from it), gitolite sets the "current subconf name" to "foo".

A "subconf" imposes some restrictions on what repos can be managed.

For example, while the subconf name is "foo", as in the above example, gitolite will only process "repo" lines for:

  • A repo called "foo".
  • A group called "@foo", as long as the group is defined in the main conf file (i.e., outside "foo.conf").
  • A member of a group called "@foo" (again, defined outside).
  • A repo that matches a member of a group called "@foo" if that member is a regular expression.

Here's an example. If the main conf file contains

@foo    =   aa bb cc/..*

then the subconf can only accept repo statements that refer to 'foo', '@foo', 'aa', 'bb', or any repo whose name starts with 'cc/'.

Note: the subconf name "master" is special; it is the default subconf in effect for the main conf file and has no restrictions.

how the "subconf name" is derived

For subconf lines that look just like include statements, i.e.,

subconf "foo/bar.conf"
subconf "frob/*.conf"
    # assume frob has files aa.conf, bb.conf

the subconf name as each file is being processed is the base name of the file. This means it would be "bar" for the first line, "aa" when processing "frob/aa.conf", and "bb" when processing "frob/bb.conf".

A variation of subconf exists that can explicitly state the subconf name:

subconf foo "frob/*.conf"

In this variation, regardless of what file in "frob/" is being read, the subconf name in effect is "foo".

security notes

group names

You can use "@group"s defined in the main config file but do not attempt to redefine or extend them in your own subconf file. If you must extend a group (say @foo) defined in the main config file, do this:

@myfoo  =   @foo
# now do whatever you want with @myfoo

Group names you define in your subconf will not clash even if the exact same name is used in another subconf file, so you need not worry about that.

delegating pubkeys

Short answer: not gonna happen.

The delegation feature is meant only for access control rules, not pubkeys. Adding/removing pubkeys is a much more significant event than changing branch level permissions for people already on staff, and only the main admin should be allowed to do it.

Gitolite's "userids" all live in the same namespace. This is unlikely to change, so please don't ask -- it gets real complicated to do otherwise. Allowing sub-admins to add users means username collisions, which also means security problems (admin-A creates a pubkey for Admin-B, thus gaining access to all of Admin-B's stuff).

If you feel the need to delegate even that, please just go the whole hog and give them separate gitolite instances (i.e., running on different servers, or at least under different gitolite hosting users on the same server)!