gitolite/doc/delegation.mkd

F=deleg delegating access control responsibilities

---

lots of repos, lots of users

Gitolite tries to make it easy to manage access to lots of users and repos, exploiting commonalities wherever possible. It lets you specify bits and pieces of the access control separately -- i.e., all the access specs for a certain repo need not be together; they can be scattered, which makes it easier to manage the sort of slice and dice needed in that example.

But eventually the config file will become too big. If you let only one person have control, he could become a bottleneck. If you give it to multiple people, they might make mistakes or stomp on each others' work accidentally.

The best way is to divide up the config file and give parts of it to different people.

Ideally, we would delegate authority for groups of repos, not individual repos, otherwise it doesn't scale. It would also be nice if we could prevent an admin from creating access rules for any repo in the system -- i.e., set limits on what repos he can control. This would be a nice "security" feature.

Delegation offers a way to do all that. You can allow access control rules for a set of repos to be specified in a subconf file and allow someone (a sub-admin) to make changes within that file. (Note: sub-admins cannot create or remove users).

how to use delegation

First, you group your repos however you want. In the example below, I'm considering firefox and lynx (projects at the root of the gitolite server) as well as any repo inside the browsers subdirectory, as members of the webbrowsers group. Similarly for the others.

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

Each of these groups is called a subconf from here on.

Then you designate a sub-admin to manage each subconf, and you ensure (using the standard gitolite feature of restricting pushes by names of changed files) that a sub-admin can make changes only to her subconf file and nothing else.

For example, Alice is in charge of all web browser development projects. Similarly, Bob takes care of web servers, and Mallory, as tradition dictates, is in charge of malware ;-)

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

Finally, you tell gitolite to pull in these files using the "subconf" command

subconf "subs/*.conf"

You can put this command anywhere in the main gitolite.conf file, but it's best to put it at the end.

Now alice can clone the admin repo, add a file called conf/subs/webbrowsers with whatever access rules she wants for the repositories under her control, commit and push.

And that's really all there is to it.

#subconf the subconf command

This command is much like the "include" command, but in addition it checks that a subconf does not contain ACL rules for repos that are outside its purview.

In the above example, the webbrowsers subconf file can only have access control lines for firefox, lynx, and anything under "browsers/" because those are the elements of the @webbrowsers group. (This is checked using a regex match, which is why "anything under browsers/" is written browsers/..*)

In more precise terms:

• the subconf name is simply the basename of the conf file, without the .conf extension, and
• the elements of an @ group of the same name are then used to limit what repos the subconf can have ACL lines for.

(Additional notes: it can also contain lines for an actual repo called webbrowsers, or, in big-config mode, for a group called @webbrowsers).

backward compatibility

For backward compatibility, if no subconf commands have been seen at the end of processing the main config file, gitolite pretends you appended

subconf "conf/fragments/*.conf"

to the end of the file.

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! It's pretty easy to setup the software itself system-wide, so that many users can use it; see the root install method in the install document.