149 lines
6.2 KiB
Markdown
149 lines
6.2 KiB
Markdown
# gitolite
|
|
|
|
Gitolite is an access control layer on top of git, which allows access control
|
|
down to the branch level, including specifying who can and cannot *rewind* a
|
|
given branch.
|
|
|
|
----
|
|
|
|
In this document:
|
|
|
|
* <a href="#what">what</a>
|
|
* <a href="#why">why</a>
|
|
* <a href="#other_features">other features</a>
|
|
* <a href="#security">security</a>
|
|
* <a href="#contact_and_license">contact and license</a>
|
|
|
|
----
|
|
|
|
<a name="what"></a>
|
|
|
|
### what
|
|
|
|
Gitolite allows a server to host many git repositories and provide access to
|
|
many developers, without having to give them real userids on or shell access
|
|
to 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/][docs] directory.
|
|
|
|
<a name="why"></a>
|
|
|
|
### why
|
|
|
|
Gitolite is separate from git, and needs to be installed and configured. So...
|
|
why do we bother?
|
|
|
|
Gitolite is useful in any server that is going to host multiple git
|
|
repositories, each with many developers, where some sort of access control is
|
|
required.
|
|
|
|
In theory, this can be done with plain old Unix permissions: each user is a
|
|
member of one or more groups, each group "owns" one or more repositories, and
|
|
using unix permissions (especially the setgid bit -- `chmod g+s`) you can
|
|
allow/disallow users access to repos.
|
|
|
|
But there are several disadvantages here:
|
|
|
|
* every user needs a userid and password on the server. This is usually a
|
|
killer...!
|
|
* adding/removing access rights involves complex `usermod -G ...` mumblings
|
|
which most admins would rather not deal with, thanks to you-know-who
|
|
* *viewing* (aka auditing) the current set of permissions requires running
|
|
multiple commands to list directories and their permissions/ownerships,
|
|
users and their group memberships, and then correlating all these manually
|
|
* auditing historical permissions or permission changes is pretty much
|
|
impossible without extraneous tools
|
|
* errors or omissions in setting the permissions exactly can cause problems
|
|
of either kind: false accepts or false rejects
|
|
* without going into ACLs it is not possible to give someone read-only
|
|
access to a repo; they either get read-write access or no access
|
|
* it is absolutely impossible to restrict pushing by branch name or tag
|
|
name.
|
|
|
|
Gitolite does away with all this:
|
|
|
|
* it uses ssh magic to remove the need to give actual unix userids to
|
|
developers
|
|
* it uses a simple but powerful config file format to specify access rights
|
|
* access control changes are affected by modifying this file, adding or
|
|
removing user's public keys, and "compiling" the configuration
|
|
* this also makes auditing trivial -- all the data is in one place, and
|
|
changes to the configuration are also logged, so you can audit them.
|
|
* finally, the config file allows distinguishing between read-only and
|
|
read-write access, not only at the repository level, but at the branch
|
|
level within repositories.
|
|
|
|
<a name="other_features"></a>
|
|
|
|
### other 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 writing gitolite.
|
|
|
|
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 somewhere in gitolite's [doc/][docs] subdirectory.
|
|
|
|
* simple, yet 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`)
|
|
* if your requirements are still too complex, you can split up the config
|
|
file and delegate authority over parts of it
|
|
* easy to specify gitweb owner, description and gitweb/daemon access
|
|
* easy to sync gitweb (http) authorisation with gitolite's access config
|
|
* 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
|
|
* specify repos using patterns (patterns may include creator's name)
|
|
* define powerful operations on the server side, even github-like forking
|
|
|
|
<a name="security"></a>
|
|
|
|
### 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 5000 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".
|
|
|
|
----
|
|
|
|
<a name="contact_and_license"></a>
|
|
|
|
### contact and license
|
|
|
|
Gitolite is released under GPL v2. See COPYING for details.
|
|
|
|
sitaramc@gmail.com
|
|
mailing list: gitolite@googlegroups.com
|
|
|
|
[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc
|