02cee1d5cf
This feature has *no* warranty, and so no documentation. Not more than
this transcript anyway.
config file:
@prof = u1
@TAs = u2 u3
@students = u4 u5 u6
repo assignments/CREATER/a[0-9][0-9]
C = @students
RW+ = CREATER
RW = WRITERS @TAs
R = READERS @prof
session:
as user "u4":
# check your permissions
$ ssh git@server
PTY allocation request failed on channel 0
hello u4, the gitolite version here is v0.95-31-gbcb14ca
you have the following permissions:
C assignments/CREATER/a[0-9][0-9]
@ @ testing
Connection to localhost closed.
# autovivify repos for assignment 12 and 24
$ git clone git@server:assignments/u4/a12 a12
Initialized empty Git repository in /home/sitaram/t/a12/.git/
Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a12.git/
warning: You appear to have cloned an empty repository.
$ git clone git@server:assignments/u4/a24 a24
Initialized empty Git repository in /home/sitaram/t/a24/.git/
Initialized empty Git repository in /home/gitolite/repositories/assignments/u4/a24.git/
warning: You appear to have cloned an empty repository.
# check what repos you autovivified
$ ssh git@server expand assignments/u4/a[0-9][0-9]
(u4) assignments/u4/a12
(u4) assignments/u4/a24
as user "u5":
# check your basic permissions
$ ssh git@server
PTY allocation request failed on channel 0
hello u5, the gitolite version here is v0.95-31-gbcb14ca
you have the following permissions:
C assignments/CREATER/a[0-9][0-9]
@ @ testing
Connection to localhost closed.
# see if you have access to any of u4's repos
$ ssh git@server expand assignments/u4/a[0-9][0-9]
# (no output produced)
as user "u4":
# allow "u5" read access to assignment 12
# note you type in "R u5", hit enter, then hit Ctrl-D. Gitolite
# then produces a confirmation message starting "New perms are:"
$ ssh git@server setperms assignments/u4/a12
R u5
New perms are:
R u5
as user "u5":
# again see if you have access to any u4 repos
$ ssh git@server expand assignments/u4/a[0-9][0-9]
(u4) assignments/u4/a12
as user "u4":
# check what permissions you gave to assignment 12
$ ssh git@server getperms assignments/u4/a12
R u5
# add RW access to "u6" to assignment 12
# again, type 'em in, then hit Ctrl-D; and note each time you run
# this you're starting from scratch -- you can't "add to" the
# permissions. Deal with it...
$ ssh git@server setperms assignments/u4/a12
R u5
RW u6
New perms are:
R u5
RW u6
as user "u6":
# check what u4 stuff you have access to
$ ssh git@server expand assignments/u4/a[0-9][0-9]
(u4) assignments/u4/a12
|
||
|---|---|---|
| conf | ||
| doc | ||
| src | ||
| .gitattributes | ||
| .gitignore | ||
| Makefile | ||
| README.mkd | ||
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.
- 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
- 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. The code is very small and easily reviewable -- the 2 programs that actually control access when a user logs in total about 220 lines of code (about 90 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.