gitolite/doc/rules.mkd

#rules access rules

This is arguably the most complex part of day-to-day gitolite. There are several interconnected ideas that make this hard to lay out easily if you're totally new to this, so read carefully.

We will use this as a running example:

@staff          =   dilbert alice wally bob

repo foo
    RW+         =   dilbert     # line 1
    RW+ dev     =   alice       # line 2
    -           =   wally       # line 3
    RW  temp/   =   @staff      # line 4
    R           =   ashok       # line 5

when does gitolite check access

The "pre-git" check is before git is invoked. Gitolite knows the repo name, user name, and attempted access (R or W), but no ref name.

The "update" check is only for write operations, and it is just before git updates a ref. This time gitolite knows the refname also.

how is a particular rule line matched

For the pre-git check, any permission that contains "R" matches a read operation, and any permission that contains "W" matches a write operation. This is because we simply don't know enough to make finer distinctions at this point.

In addition, gitolite ignores deny rules during the pre-git check. (You can [change this][deny-rules] if you wish, though it's rarely needed). This means line 3 is ignored, and so Wally in our example will pass the pre-git check.

For the update check, git gives us all the information we need. Then:

• all the rules for a repo are [accumulated][rule-accum]

• then the rules pertaining to this repo and this user (or to a group to which they belong, respectively) are kept; the rest are ignored

• these rules are examined in the sequence they appeared in the conf file. For each rule:

  • if the ref does not match the [refex][], the rule is skipped
  • if it's a deny rule (the permissions field is a -), access is rejected and the matching stops
  • if the permission field matches the specific [type of write][write-types] operation, access is allowed and the matching stops

• if no rule ends with a decision, ("fallthru"), access is rejected.

Now you need to understand how [refex][] matching happens and how the permissions match the various [types of write operations][write-types].

Using these, you can see, in our example, that:

• everyone, even wally, can read the repo.
• dilbert can push, rewind, or delete any ref.
• alice can push, rewind, or delete any ref whose name starts with 'dev'; see [refex][] for details.
• alice can also push (but not rewind or delete) any ref whose name starts with 'temp/'. This applies to bob also.
• if it weren't for line 3, the previous statement would apply to wally also.

Interestingly, wally can get past the pre-git check because gitolite ignores deny rules for pre-git, but having got past it, he can't actually do anything. That's by design, and as I said if you don't like it you can ask gitolite to [deny at pre-git][deny-rules].

summary of permissions

The full set of permissions, in regex syntax: -|R|RW+?C?D?M?. This expands to one of -, R, RW, RW+, RWC, RW+C, RWD, RW+D, RWCD, or RW+CD, all but the first one optionally followed by an M. And by now you know what they all mean.