364a2317c2
enough people told me they want one because they don't watch the git ML or it's too high traffic, so I finally made one and invited a few folks.
112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# gitolite
|
|
|
|
> [Update 2009-10-28: apart from all the nifty new features, there's now an
|
|
> "easy install" script in the src directory. This script can be used to
|
|
> install as well as upgrade a gitolite install. Please see the INSTALL
|
|
> document 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, and more, are documented in
|
|
detail [here][gsdiff].
|
|
|
|
[gsdiff]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#diff
|
|
|
|
* 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
|
|
* apart from branch-name based restrictions, you can also restrict by
|
|
file/dir name changed (i.e., output of `git diff --name-only`)
|
|
* 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
|
|
* easier to specify gitweb owner, description and gitweb/daemon access
|
|
* easier to sync gitweb (http) authorisation with gitolite's access config
|
|
* 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 at the branch/tag level
|
|
|
|
### 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.
|
|
|
|
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
|
|
:-)
|
|
|
|
However, there are a few optional features (which must be explicitly enabled
|
|
in the RC file) where I just haven't had the time to reason about security
|
|
thoroughly enough. Please read the comments in `conf/example.gitolite.rc` for
|
|
details, looking for the word "security".
|
|
|
|
----
|
|
|
|
### contact and license
|
|
|
|
Gitolite is released under GPL v2. See COPYING for details.
|
|
|
|
sitaramc@gmail.com
|
|
mailing list: gitolite@googlegroups.com
|