gitolite/doc/rules.mkd
Sitaram Chamarty de40461d9a document overhaul
- explicit 'list' gives way to mindmap, ...
  - 'fm2mt.pl' to produce master-toc.mkd from the mindmap
  - mkdoc no longer ignores master-toc.mkd, calls fm2mt.pl itself

and LOTS of changes to the actual docs
2012-04-05 21:42:22 +05:30

152 lines
4.9 KiB
Markdown

## #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
### what does a rule look like?
A rule line has the structure
<permission> <zero or more refexes> = <one or more users/user groups>
The most common permissions used are:
* R, for read only
* RW, for push existing ref or create new ref
* RW+, for "push -f" or ref deletion allowed (i.e., destroy
information)
* `-` (the minus sign), to **deny** access.
There are also other, less commonly used, [types of permissions][write-types].
A refex is an expression that matches the ref (i.e., branch or tag) being
pushed. See [this][refex] for more info.
### when are the rules checked?
There are 2 places where access rules are checked.
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 are the rules 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]
* 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].
### #perms 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 two optionally followed by an `M`. And by now you
know what they all mean.
## additional topics
### #rule-accum rule accumulation
Gitolite was meant to collect rules from multiple places and apply them all.
For example, this:
repo foo
RW = u1
@gr1 = foo bar
repo @gr1
RW = u2
R = u3
repo @all
R = gitweb
is effectively the same as this, for repo foo:
repo foo
RW = u1
RW = u2
R = u3
R = gitweb
This extends to patterns also, but I'll leave an example for later.
### #deny-rules applying deny rules during the pre-git check
The access rules section above describes the problem in one scenario. Here's
another. Let's say you have this at the end of your gitolite.conf file:
repo @all
R = gitweb daemon
but you don't want the gitolite-admin repo showing up on gitweb. How do you
do that? Here's how:
repo gitolite-admin
- = gitweb daemon
option deny-rules = 1
repo @all
R = gitweb daemon
Note that the order matters; the `-` rule must come *before* the `R` rule.