gitolite/doc/delegation.mkd

## delegating access control responsibilities

In this document:

  * <a href="#_lots_of_repos_lots_of_users">lots of repos, lots of users</a>
  * <a href="#_how_to_use_delegation">how to use delegation</a>
      * <a href="#_the_subconf_command">the subconf command</a>
      * <a href="#_backward_compatibility">backward compatibility</a>
  * <a href="#_security_notes">security notes</a>
      * <a href="#_group_names">group names</a>
      * <a href="#_delegating_pubkeys">delegating pubkeys</a>

----

<a name="_lots_of_repos_lots_of_users"></a>

### 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).

<a name="_how_to_use_delegation"></a>

### 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][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.

<a name="_the_subconf_command"></a>

#### 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`).

<a name="_backward_compatibility"></a>

#### 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.

<a name="_security_notes"></a>

### security notes

<a name="_group_names"></a>

#### 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.

<a name="_delegating_pubkeys"></a>

#### 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.