198 lines
8.4 KiB
Markdown
198 lines
8.4 KiB
Markdown
<a name="start"></a>
|
|
|
|
# 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.
|
|
|
|
Gitolite comes with a **huge** amount of documentation. If you're absolutely
|
|
new, the suggested reading order is this:
|
|
|
|
* the README (this document) for a quick intro
|
|
* the [INSTALL][install] document
|
|
* the [ADMIN][admin] document
|
|
|
|
If you run into trouble start [here](#support). If you're migrating from
|
|
gitosis, read [this][migr].
|
|
|
|
And [here][who]'s some information on some of the projects and people using
|
|
gitolite (and who, in turn, have helped shape its features).
|
|
|
|
Once you've installed it and started using it, you'll want to explore some of
|
|
the more powerful features. All the documentation is available in the source
|
|
repo as well as [online][docs]. All the longer documents have tables of
|
|
contents, so you can quickly get a feel for what is covered right at the top.
|
|
|
|
----
|
|
|
|
In this document:
|
|
|
|
* <a href="#_what">what</a>
|
|
* <a href="#_why">why</a>
|
|
* <a href="#_main_features">main features</a>
|
|
* <a href="#_support">support</a>
|
|
* <a href="#_security">security</a>
|
|
* <a href="#_contact_and_license">contact and license</a>
|
|
|
|
----
|
|
|
|
<a name="_what"></a>
|
|
|
|
### what
|
|
|
|
Gitolite lets you use a single user on 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, especially in tightly controlled environments
|
|
* adding/removing access rights involves complex `usermod -G ...` mumblings
|
|
which most admins would rather not deal with
|
|
* *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="_main_features"></a>
|
|
|
|
### main 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="support"></a>
|
|
|
|
<a name="_support"></a>
|
|
|
|
### support
|
|
|
|
Most installation problems are caused by not knowing ssh. Take a look at this
|
|
[transcript][] to see how simple it actually is, if your server's ssh daemon
|
|
is behaving itself.
|
|
|
|
If I suspect your problem is an ssh issue, I will probably ignore it. Please
|
|
learn how [gitolite uses ssh][doc9gas] and then methodically go through the
|
|
[ssh trouble shooting][doc6sts] document. These two documents contain
|
|
everything I could possibly tell you. I have nothing to add.
|
|
|
|
Even for other topics, please look through at least the table of contents of
|
|
at least the numbered documents to see if your question is already answered,
|
|
before asking.
|
|
|
|
<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.
|
|
|
|
* author: sitaramc@gmail.com, sitaram@atc.tcs.com
|
|
* mailing list: gitolite@googlegroups.com
|
|
* list subscribe address : gitolite+subscribe@googlegroups.com
|
|
|
|
[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd
|
|
[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd
|
|
[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
|
|
[migr]: http://github.com/sitaramc/gitolite/blob/pu/doc/migrate.mkd
|
|
[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc
|
|
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd
|
|
[doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd
|
|
[who]: http://github.com/sitaramc/gitolite/blob/pu/doc/who-uses-it.mkd
|
|
|