doc fixes...
- README: add a "what" section first, plus a few minor fixes
- doc/5:
- remove reference to obsolete ml branch URL; point it to the right
place with the right section name
- change text to reflect the fact that p-t-a is now the default!
This commit is contained in:
Sitaram Chamarty
parent
8e47e0117a
commit
536e3198bf
33
README.mkd
33
README.mkd
|
|
@ -15,13 +15,28 @@ specifying who can and cannot *rewind* a given branch.
|
|||
|
||||
In this document:
|
||||
|
||||
* what
|
||||
* why
|
||||
* what's extra
|
||||
* extra features
|
||||
* security
|
||||
* contact and license
|
||||
|
||||
----
|
||||
|
||||
### what
|
||||
|
||||
Gitolite allows a server to host many git repositories and provide access to
|
||||
many developers, without having to give them real userids on the server. The
|
||||
essential magic in doing this is ssh's pubkey access and the `authorized_keys`
|
||||
file, and the inspiration was an older program called gitosis.
|
||||
|
||||
Gitolite can restrict who can read from (clone/fetch) or write to (push) a
|
||||
repository. It can also restrict who can push to what branch or tag, which is
|
||||
very important in a corporate environment. Gitolite can be installed without
|
||||
requiring root permissions, and with no additional software than git itself
|
||||
and perl. It also has several other neat features described below and
|
||||
elsewhere in the `doc/` directory.
|
||||
|
||||
### why
|
||||
|
||||
I have been using gitosis for a while, and have learnt a lot from it. But in
|
||||
|
|
@ -33,15 +48,15 @@ a typical $DAYJOB setting, there are some issues:
|
|||
to help remotely, we never did manage to install it eventually)
|
||||
* you don't have root access, or the ability to add users (this is also true
|
||||
for people who have just one userid on a hosting provider)
|
||||
* the most requested feature (see "what's new?") had to be written anyway
|
||||
* the most requested feature (see below) had to be written anyway
|
||||
|
||||
All of this pointed to a rewrite. In perl, naturally :-)
|
||||
|
||||
### what's extra
|
||||
### extra features
|
||||
|
||||
**Per-branch permissions**. You will not believe how often I am asked this at
|
||||
$DAYJOB. This is almost the single reason I started *thinking* about rolling
|
||||
my own gitosis in the first place.
|
||||
The most important feature I needed was **per-branch permissions**. This is
|
||||
pretty much mandatory in a corporate environment, and is almost the single
|
||||
reason I started *thinking* about rolling my own gitosis in the first place.
|
||||
|
||||
It's not just "read-only" versus "read-write". Rewinding a branch (aka "non
|
||||
fast forward push") is potentially dangerous, but sometimes needed. So is
|
||||
|
|
@ -53,8 +68,8 @@ Here're **some more features**. All of them are documented in detail
|
|||
somewhere in the `doc/` subdirectory.
|
||||
|
||||
* simpler, yet far more powerful, config file syntax, including specifying
|
||||
gitweb/daemon access. You'll need this power if you manage lots of users
|
||||
+ repos + combinations of access
|
||||
gitweb/daemon access. You'll need this power if you manage lots of
|
||||
users+repos+combinations of access
|
||||
* config file syntax gets checked upfront, and much more thoroughly
|
||||
* if your requirements are still too complex, you can split up the config
|
||||
file and delegate authority over parts of it
|
||||
|
|
@ -62,7 +77,7 @@ somewhere in the `doc/` subdirectory.
|
|||
a synonym for "annotate" :-)]
|
||||
* "personal namespace" prefix for each dev
|
||||
* migration guide and simple converter for gitosis conf file
|
||||
* "exclude" (or "deny" rights in the config file) -- this is the "rebel"
|
||||
* "exclude" (or "deny") rights in the config file -- this is the "rebel"
|
||||
branch in the repository, and always will be ;-)
|
||||
|
||||
### security
|
||||
|
|
|
|||
|
|
@ -5,14 +5,14 @@
|
|||
### 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. (The example under "simpler, more
|
||||
powerful syntax" [here][ml] should give you an idea). As you can see, 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
|
||||
exploiting commonalities wherever possible. (The example in the section
|
||||
"simpler syntax" in [this page][ml] should give you an idea). As you can see,
|
||||
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.
|
||||
|
||||
[ml]: http://github.com/sitaramc/gitolite/blob/ml/update.mkd
|
||||
[ml]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd
|
||||
|
||||
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
|
||||
|
|
@ -81,23 +81,24 @@ Splitting up the file does help, but there's also that little security issue
|
|||
-- anyone can make any change to any "fragment", unless you (once again) go
|
||||
back to Unix permissions to keep them separate.
|
||||
|
||||
Fixing that requires using "push-to-admin".
|
||||
Fixing that requires using "push-to-admin", which is the default (and only)
|
||||
method to make config changes in gitosis.
|
||||
|
||||
The page on [push-to-admin][ptd] explains clearly how to set it up. Unlike
|
||||
gitosis, I refuse to make it the default because it's a support nightmare.
|
||||
Don't get me wrong -- it's a great feature, and I use it myself, but the
|
||||
learning curve is too steep to make it *required*.
|
||||
For a long time, I refused to make "push to admin" the default because it's a
|
||||
support nightmare. Don't get me wrong -- it's a great feature, and I use it
|
||||
myself, but the learning curve was too steep to make it *required*.
|
||||
|
||||
[ptd]: http://github.com/sitaramc/gitolite/blob/pu/doc/4-push-to-admin.mkd
|
||||
But eventually I figured out a way to front-load the darn ssh problem that
|
||||
everyone on #git seemed to run up against, created a nice "easy install"
|
||||
script, and made "push to admin" the default.
|
||||
|
||||
So, having setup push-to-admin, you add these lines to the main config file,
|
||||
assuming Alice is 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 ;-)
|
||||
So now, you just add these lines to the main config file, assuming Alice is 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 probably added these two lines while setting up push-to-admin
|
||||
# these 2 lines were probably present already
|
||||
repo gitolite-admin
|
||||
RW+ = sitaram
|
||||
# now add these 3 lines
|
||||
|
|
@ -111,10 +112,10 @@ of malware ;-)
|
|||
@webserver_repos = apache nginx
|
||||
@malware_repos = conficker storm
|
||||
|
||||
**As you can see, for each repo group you want to delegate authority over,
|
||||
there's a *branch* in the `gitolite-admin` repo with the same name. If you
|
||||
As you can see, **for each repo group** you want to delegate authority over,
|
||||
there's a **branch with the same name** in the `gitolite-admin` repo. If you
|
||||
have write access to that branch, you are allowed to define rules for repos in
|
||||
that repo group.**
|
||||
that repo group.
|
||||
|
||||
In other words, we use gitolite's per-branch permissions to "enforce" the
|
||||
separation between the delegated configs!
|
||||
|
|
|
|||
Loading…
Reference in a new issue