gitolite/doc/rules.mkd

83 lines
3.3 KiB
Markdown
Raw Normal View History

2012-03-16 02:54:47 +01:00
## #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*. <font
color="gray">(You can [change this][deny-rules] if you wish, though it's
rarely needed)</font>. 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.