gitolite/doc/delegation.mkd

## delegating access control responsibilities

[Thanks to jeromeag for forcing me to think through this...]

----

In this document:

  * <a href="#_lots_of_repos_lots_of_users">lots of repos, lots of users</a>
  * <a href="#_splitting_up_the_set_of_repos_into_groups">splitting up the set of repos into groups</a>
  * <a href="#_delegating_ownership_of_groups_of_repos">delegating ownership of groups of repos</a>
  * <a href="#_other_notes">other notes</a>
  * <a href="#_security_philosophy_note">security/philosophy note</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.  Note that delegated admins cannot
create or remove users, nor can they define new repos.  They can only define
access control rules for a set of repos they have been given authority for.

----

It's easier to show how it all works with an example instead of long
descriptions.

<a name="_splitting_up_the_set_of_repos_into_groups"></a>

### splitting up the set of repos into groups

To start with, recall that gitolite allows you to specify **groups** (of users
or repos, same syntax).  So the basic idea is that the main config file
(`conf/gitolite.conf` in your admin repo clone) will specify some repo groups:

    # group your projects/repos however you want
    @webbrowser_repos           = firefox lynx
    @webserver_repos            = apache nginx
    @malware_repos              = conficker storm

    # any other config as usual, including access control lines for any of the
    # above projects or groups

<a name="_delegating_ownership_of_groups_of_repos"></a>

### delegating ownership of groups of repos

Once the repos are grouped, give each person charge of one or more groups.
For example, Alice may be in charge of all web browser development projects,
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

You do this by adding files with specific names to the `gitolite-admin` repo:

    # 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/fragments/webbrowser_repos    = alice
        RW  NAME/conf/fragments/webserver_repos     = bob
        RW  NAME/conf/fragments/malware_repos       = mallory

This uses gitolite's ability to restrict pushes by file/dir name being changed
-- the syntax you see above ensures that, while "sitaram" does not have any
NAME based restrictions, the other 3 users do.  See `conf/example.conf` for
syntax and notes.

As you can see, **for each repo group** you want to delegate authority over,
there's a rule for a **corresponding file** in `conf/fragments` in the
`gitolite-admin` repo.  If you have write access to that file, you are allowed
to define rules for repos in that repo group.

In other words, we use gitolite's file/dir NAME-based permissions to "enforce"
the separation between the delegated configs!

Here's how to use this in practice:

  * Alice clones the `gitolite-admin` repo, and adds a file called
    `conf/fragments/webbrowser_repos.conf`

  * she writes in this file any access control rules for the "firefox" and
    "lynx" repos.  She should not write access rules for any other project --
    they will be ignored

  * Alice then commits and pushes to the `gitolite-admin` repo

Naturally, a successful push invokes the post-update hook that the admin repo
has, which eventually runs the compile script.  The **net effect** is as if
you appended the contents of all the "fragment" files, in alphabetical order,
to the bottom of the main file.

<a name="_other_notes"></a>

### other notes

The "include" statement cannot be used in fragment files, for security
reasons.

----

<a name="_security_philosophy_note"></a>

### security/philosophy note

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 delegated 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 without all the
"easy install" fuss.  See the "system install / user setup" section in
doc/1-INSTALL.mkd for details.