gitolite.conf by example
inspired by someone I would prefer not to have as a user, but hopefully it will help others with more genuine problems.
This commit is contained in:
Sitaram Chamarty
parent
f0cedeb04f
commit
26155c4027
238
doc/gitolite.conf-by-example.mkd
Normal file
238
doc/gitolite.conf-by-example.mkd
Normal file
|
|
@ -0,0 +1,238 @@
|
|||
# gitolite.conf -- by example
|
||||
|
||||
I hate people who make statements like "I dont have time to learn". People
|
||||
with that sort of attitude shouldn't use gitolite at all, and I refuse to
|
||||
spoon-feed them or be their personal tutor.
|
||||
|
||||
However, it's possible that even with the right attitude and willingness to
|
||||
learn, some people just get a mental block about something, and so I figure
|
||||
this might help.
|
||||
|
||||
(Side note: followup questions not welcome from people in the former category;
|
||||
you know who you are).
|
||||
|
||||
**WARNING 1**: in case of conflict between this document and reality, reality
|
||||
wins. For conflict between this document and the [main document][conf], the
|
||||
main document wins. In any case, please bring such issues to my notice.
|
||||
|
||||
**WARNING 2**: this document has examples only for the most commonly used
|
||||
features. If you don't find a feature here, look in the main document before
|
||||
asking me.
|
||||
|
||||
**WARNING 3**: Read the WHOLE document. I can't keep saying, for instance,
|
||||
that "rewind" actually means any of 3 different things so I'll say it only
|
||||
once. It's upto you to have read that part also.
|
||||
|
||||
[conf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
|
||||
|
||||
----
|
||||
|
||||
[[TOC]]
|
||||
|
||||
----
|
||||
|
||||
### general notes
|
||||
|
||||
Git branch/tag name **recap**: branches look like refs/heads/something, tags
|
||||
look like refs/tags/something. When there is no ambiguity, we leave out the
|
||||
refs/heads/ and the refs/tags/.
|
||||
|
||||
A "rewind" means any of 3 things: force-push a branch (make it go backward,
|
||||
using 'git push -f' or equivalent), delete a branch, or update a tag. The
|
||||
first two are clearly information-losing operations so it is wise to require
|
||||
special rights to do them. The third is in the same category because tags are
|
||||
supposed to be "write once" so **re**-writing a tag is considered abnormal.
|
||||
|
||||
These examples are only for the more complex parts of the conf file. We're
|
||||
not going to discuss things like what characters are allowed in a username or
|
||||
reponame, how to write a comment line, how to write continuation lines (you
|
||||
can't), include files, and all such *lexical* issues.
|
||||
|
||||
### extremely brief regex overview
|
||||
|
||||
Regexes are powerful. Gitolite uses that power as much as it can. If you
|
||||
can't handle that power, hire someone who can and become a manager.
|
||||
|
||||
That said, here's a very quick overview of the highlights.
|
||||
|
||||
`^` and `$` are called "anchors". They anchor the match to the beginning and
|
||||
end of the string respectively.
|
||||
|
||||
^foo matches any string starting with 'foo'
|
||||
foo$ matches any string ending with 'foo'
|
||||
^foo$ matches exact string 'foo'.
|
||||
|
||||
To be precise, the last one is "any string starting and ending with *the same*
|
||||
'foo'". (Without the italicised phrase, it could mean "foofoo" would also
|
||||
match, but it doesn't).
|
||||
|
||||
`[0-9]` is an example of a character class; this one matches any single digit.
|
||||
`[a-z]` matches any lower case alpha. For example, `[0-9a-f]` is the range of
|
||||
hex characters. You can guess what `[a-zA-Z0-9_]` does, then.
|
||||
|
||||
`.` (the period) is special -- it matches any character. If you want to match
|
||||
an actual period, you need to say `\.`.
|
||||
|
||||
`*`, `?`, and `+` are quantifiers. They apply to the previous token. `a*`
|
||||
means "zero or more 'a' characters". Similarly `a+` means "one or more", and
|
||||
`a?` means "zero or one".
|
||||
|
||||
As a result, `.*` means "any number (including zero) of any character".
|
||||
|
||||
The previous token need not be a single character; you can use parens to make
|
||||
it longer. `(foo)+` matches one or more "foo", (like "foo", "foofoo",
|
||||
"foofoofoo", etc.)
|
||||
|
||||
### basic access control
|
||||
|
||||
repo gitolite-admin
|
||||
RW+ = sitaram
|
||||
# this is equivalent to:
|
||||
RW+ refs/.* = sitaram
|
||||
|
||||
Sitaram is the only admin. He can push, create, delete, or rewind any branch
|
||||
or tag in the gitolite-admin repo.
|
||||
|
||||
repo testing
|
||||
RW+ = @all
|
||||
|
||||
The 'testing' repo is a play area for everyone. Anyone can do anything to any
|
||||
branch or tag on it.
|
||||
|
||||
repo foo
|
||||
RW+ = sitaram dilbert
|
||||
RW = alice ashok
|
||||
R = wally
|
||||
|
||||
Wally can only read the repo. Alice and Ashok can push but not rewind; only
|
||||
Sitaram and Dilbert can do that.
|
||||
|
||||
R master = wally # MEANINGLESS! WONT DO WHAT YOU THINK IT DOES!!
|
||||
|
||||
This won't work. You can only restrict "read" access at the repo level not
|
||||
the branch level. This is a git issue, not a gitolite issue. Go bother them,
|
||||
or switch to gerrit.
|
||||
|
||||
repo foo
|
||||
RW master$ = dilbert alice
|
||||
# this is equivalent to:
|
||||
RW refs/heads/master$ = dilbert alice
|
||||
|
||||
The reason for treating "master$" as "refs/heads/master$" is that matching
|
||||
branches is the most common use so we made it convenient to use. Anything
|
||||
*not* starting with `refs/` (or `NAME/`, but that is out of scope of this
|
||||
document), is implicitly prefixed with `refs/heads/`).
|
||||
|
||||
The `master$` is called a "refex" (a regex that matches a ref).
|
||||
|
||||
Dilbert and Alice can push to the "master" branch. Unless some other rule
|
||||
allows it, they cannot push to, say, "master1", "masterfull" etc., due to the
|
||||
`$` at the end of the refex.
|
||||
|
||||
This rule does not match "headmaster"; refexes are treated as if they have a
|
||||
`^` at the start. (This means `^refs/heads/master` in this case, not
|
||||
`^master`, in case you forgot!)
|
||||
|
||||
RW+ pu = dilbert
|
||||
# again, remember this is equivalent to:
|
||||
RW+ refs/heads/pu = dilbert
|
||||
|
||||
Dilbert can push any branch whose name starts with "pu". This includes "pu1",
|
||||
"pupu", "pu/up", and so on, not just "pu". This is because there is no `$` at
|
||||
the end.
|
||||
|
||||
RW junk/ = wally
|
||||
|
||||
Wally can push any branch under "junk/", which means "junk/foo", "junk/bar",
|
||||
are ok but not "junk1" or even "junk".
|
||||
|
||||
RW tmp/ = @all
|
||||
|
||||
Similar to above, but for *any* authenticated user.
|
||||
|
||||
RW refs/tags/v[0-9] = ashok # the QA guy
|
||||
|
||||
Ashok is allowed to push version tags. He can push any tag whose name starts
|
||||
with a "v", then a digit, like "v1", "v1.0", "v2.0rc1", etc., but not "v-1",
|
||||
"ver1".
|
||||
|
||||
### advanced access control
|
||||
|
||||
#### "deny" rules
|
||||
|
||||
**Warning**: When using deny rules, the order of your rules matters, where
|
||||
earlier it did not.
|
||||
|
||||
PROCESSING LOGIC:
|
||||
|
||||
> The first matching refex that has the permission you're looking for (`W`
|
||||
> or `+`) **or a minus (`-`)**, results in success **or failure,
|
||||
> respectively**. A fallthrough **also** results in failure.
|
||||
|
||||
RW refs/tags/v[0-9] = ashok
|
||||
- refs/tags/v[0-9] = @staff
|
||||
RW refs/tags = @staff
|
||||
|
||||
This allows only Ashok to write "version tags" (see rule for Ashok the QA guy
|
||||
somewhere above). The others can write any tags they want, *except* version
|
||||
tags. To understand this, try and match each rule *in sequence* with the name
|
||||
of the tag being pushed, and the user doing it, applying the logic described
|
||||
earlier.
|
||||
|
||||
* for non-version tags, only the 3rd rule matches, so anyone on staff can
|
||||
push them
|
||||
* for version tags by bruce, the first rule matches so he can push them
|
||||
* for version tags by staffers *other than bruce*, the second rule matches
|
||||
before the third one, and it has a `-` as the permission, so the push
|
||||
fails
|
||||
|
||||
#### personal branches
|
||||
|
||||
Personal branches exist **in a namespace** of their own. The syntax is
|
||||
|
||||
RW personal/USER/ = @staff
|
||||
|
||||
where the "personal" can be anything you like (but cannot be empty), and the
|
||||
"/USER/" part is **necessary**. A user "alice" can then push any branches
|
||||
inside `personal/alice/`. Which means she can push `personal/alice/foo` and
|
||||
`personal/alice/bar`, but NOT `personal/alice`.
|
||||
|
||||
#### splitting up rules into rulesets
|
||||
|
||||
Rules accumulate. Even when separated by rules for other repos. They
|
||||
accumulate intuitively. For example:
|
||||
|
||||
repo foo
|
||||
RW+ = alice
|
||||
|
||||
repo bar
|
||||
RW+ = dilbert
|
||||
|
||||
repo @all
|
||||
RW dev/USER/ = @staff
|
||||
|
||||
repo foo
|
||||
RW+ tmp/ = @staff
|
||||
|
||||
has the **effective** ruleset, for repo foo, of
|
||||
|
||||
repo foo
|
||||
RW+ = alice
|
||||
RW dev/USER/ = @staff
|
||||
RW+ tmp/ = @staff
|
||||
|
||||
Just remember that if you use [deny rules][dr] anywhere then the *order of the
|
||||
rules matters*!
|
||||
|
||||
[dr]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_deny_rules
|
||||
|
||||
#### gitweb and daemon
|
||||
|
||||
Gitolite does NOT do anything for gitweb and daemon access **except**
|
||||
|
||||
* for daemon, create the file `git-daemon-export-ok` in the repository
|
||||
* for gitweb, add the repo (plus owner name, if given) to the list of
|
||||
projects to be served by gitweb (see the config file variable
|
||||
`$PROJECTS_LIST`, which should have the same value you specified for
|
||||
`$projects_list` when setting up gitweb)
|
||||
* put the description, if given, in `$repo/description`
|
||||
Loading…
Reference in a new issue