536e3198bf
- 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!
106 lines
4.3 KiB
Markdown
106 lines
4.3 KiB
Markdown
# gitolite
|
|
|
|
> [IMPORTANT: There is now an "upgrade" document in the "doc" directory;
|
|
> please read if upgrading gitolite]
|
|
|
|
> [Update 2009-10-10: apart from all the nifty new features, there's now an
|
|
> "easy install" script in the src directory. Please see the INSTALL
|
|
> document in the doc directory for details]
|
|
|
|
----
|
|
|
|
Gitolite is a rewrite of gitosis, with a completely different config file that
|
|
allows (at last!) access control down to the branch level, including
|
|
specifying who can and cannot *rewind* a given branch.
|
|
|
|
In this document:
|
|
|
|
* what
|
|
* why
|
|
* 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
|
|
a typical $DAYJOB setting, there are some issues:
|
|
|
|
* it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get)
|
|
and be done
|
|
* often, "python-setuptools" isn't installed (and on a Solaris9 I was trying
|
|
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 below) had to be written anyway
|
|
|
|
All of this pointed to a rewrite. In perl, naturally :-)
|
|
|
|
### extra features
|
|
|
|
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
|
|
deleting a branch (which is really just an extreme form of rewind). I needed
|
|
something in between allowing anyone to do it (the default) and disabling it
|
|
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
|
|
|
|
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
|
|
* 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
|
|
* more comprehensive logging [aka: management does not think "blame" is just
|
|
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"
|
|
branch in the repository, and always will be ;-)
|
|
|
|
### security
|
|
|
|
Due to the environment in which this was created and the need it fills, I
|
|
consider this a "security" program, albeit a very modest one. The code is
|
|
very small and easily reviewable -- the 2 programs that actually control
|
|
access when a user logs in total about 200 lines of code (about
|
|
80 lines according to "sloccount").
|
|
|
|
For the first person to find a security hole in it, defined as allowing a
|
|
normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
|
|
that the config file says he shouldn't, and caused by a bug in *code* that is
|
|
in the "master" branch, (not in the other branches, or the configuration file
|
|
or in Unix, perl, shell, etc.)... well I can't afford 1000 USD rewards like
|
|
djb, so you'll have to settle for 1000 INR (Indian Rupees) as a "token" prize
|
|
:-)
|
|
|
|
----
|
|
|
|
### contact and license
|
|
|
|
Gitolite is released under GPL v2. See COPYING for details.
|
|
|
|
sitaramc@gmail.com
|