# 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 [this][NAME] gitolite feature) 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][abe] dictates, is in charge of malware ;-) [abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters # 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.