deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

*major* doc revamp

Browse source 
people will NOT read documentation, especially the bloody install
documentation.  I'm about ready to throw in the towel and declare
gitolite unsupported, take-it-or-leave-it.

But I'm making one last attempt to refocus the install doc to better
suit the "I know I'm very smart and I dont have to read docs so it's
clearly your fault that I am not able to install gitolite" crowd.

As a bonus, though, I ended up making proper, hyper-linked, TOCs for
most of the docs, and moved a whole bunch of stuff around.  Also finally
got some of the ssh stuff over from my git-notes repo because it really
belongs here.
This commit is contained in:
Sitaram Chamarty 2010-05-21 17:53:05 +05:30
parent 025de395dc
commit 196b41e0fd
16 changed files with 930 additions and 557 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

111
README.mkd
View file

@ -1,60 +1,92 @@
# gitolite # gitolite
> [Update 2009-10-28: apart from all the nifty new features, there's now an Gitolite is an access control layer on top of git, which allows access control
> "easy install" script in the src directory. This script can be used to down to the branch level, including specifying who can and cannot *rewind* a
> install as well as upgrade a gitolite install. Please see the INSTALL given branch.
> 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: In this document:
* what * <a href="#A1">what</a>
* why * <a href="#A2">why</a>
* extra features * <a href="#A3">other features</a>
* security * <a href="#A4">security</a>
* contact and license * <a href="#A5">contact and license</a>
---- ----
<a name="A1"></a>
### what ### what
Gitolite allows a server to host many git repositories and provide access to 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 many developers, without having to give them real userids on or shell access
essential magic in doing this is ssh's pubkey access and the `authorized_keys` to the server. The essential magic in doing this is ssh's pubkey access and
file, and the inspiration was an older program called gitosis. 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 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 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 very important in a corporate environment. Gitolite can be installed without
requiring root permissions, and with no additional software than git itself requiring root permissions, and with no additional software than git itself
and perl. It also has several other neat features described below and and perl. It also has several other neat features described below and
elsewhere in the `doc/` directory. elsewhere in the [doc/][docs] directory.
<a name="A2"></a>
### why ### why
I have been using gitosis for a while, and have learnt a lot from it. But in Gitolite is separate from git, and needs to be installed and configured. So...
a typical $DAYJOB setting, there are some issues: why do we bother?
* it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get) Gitolite is useful in any server that is going to host multiple git
and be done repositories, each with many developers, where some sort of access control is
* often, "python-setuptools" isn't installed (and on a Solaris9 I was trying required.
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 :-) 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.
### extra features 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="A3"></a>
### other features
The most important feature I needed was **per-branch permissions**. This is The most important feature I needed was **per-branch permissions**. This is
pretty much mandatory in a corporate environment, and is almost the single 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. reason I started *thinking* about writing gitolite.
It's not just "read-only" versus "read-write". Rewinding a branch (aka "non 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 fast forward push") is potentially dangerous, but sometimes needed. So is
@ -63,28 +95,27 @@ something in between allowing anyone to do it (the default) and disabling it
completely (`receive.denyNonFastForwards` or `receive.denyDeletes`). completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
Here're **some more features**. All of them, and more, are documented in Here're **some more features**. All of them, and more, are documented in
detail [here][gsdiff]. detail somewhere in gitolite's [doc/][docs] subdirectory.
[gsdiff]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#diff * simple, yet powerful, config file syntax, including specifying
* simpler, yet far more powerful, config file syntax, including specifying
gitweb/daemon access. You'll need this power if you manage lots of gitweb/daemon access. You'll need this power if you manage lots of
users+repos+combinations of access users+repos+combinations of access
* apart from branch-name based restrictions, you can also restrict by * apart from branch-name based restrictions, you can also restrict by
file/dir name changed (i.e., output of `git diff --name-only`) 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 * if your requirements are still too complex, you can split up the config
file and delegate authority over parts of it file and delegate authority over parts of it
* easier to specify gitweb owner, description and gitweb/daemon access * easy to specify gitweb owner, description and gitweb/daemon access
* easier to sync gitweb (http) authorisation with gitolite's access config * easy to sync gitweb (http) authorisation with gitolite's access config
* more comprehensive logging [aka: management does not think "blame" is just * comprehensive logging [aka: management does not think "blame" is just a
a synonym for "annotate" :-)] synonym for "annotate" :-)]
* "personal namespace" prefix for each dev * "personal namespace" prefix for each dev
* migration guide and simple converter for gitosis conf file * migration guide and simple converter for gitosis conf file
* "exclude" (or "deny") rights at the branch/tag level * "exclude" (or "deny") rights at the branch/tag level
* specify repos using patterns (patterns may include creator's name) * specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking * define powerful operations on the server side, even github-like forking
<a name="A4"></a>
### security ### security
Due to the environment in which this was created and the need it fills, I Due to the environment in which this was created and the need it fills, I
@ -105,9 +136,13 @@ details, looking for the word "security".
---- ----
<a name="A5"></a>
### contact and license ### contact and license
Gitolite is released under GPL v2. See COPYING for details. Gitolite is released under GPL v2. See COPYING for details.
sitaramc@gmail.com sitaramc@gmail.com
mailing list: gitolite@googlegroups.com mailing list: gitolite@googlegroups.com
[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc

28
contrib/autotoc Executable file
View file

@ -0,0 +1,28 @@
#!/usr/bin/perl -w
# filter gitolite's mkd files through this; it's designed to be idempotent of
# course
undef $/;
$doc = <>;
$doc =~ s/^<a name="A\d+"><\/a>\n\n//mg;
@toc = $doc =~ /^###.*/mg;
$i = 0;
$doc =~ s/^###/$i++; "<a name=\"A$i\"><\/a>\n\n###"/mge;
$i = 0;
for (@toc) {
$i++;
s/### (.*)/ * <a href="#A$i">$1<\/a>/;
s/^(#+)/' ' x length($1)/e;
}
$toc = "In this document:\n\n";
$toc .= join("\n", @toc);
$toc .= "\n\n";
$doc =~ s/^In this document:\n\n.*?\n\n/$toc/sm;
print $doc;

494
doc/0-INSTALL.mkd
View file

@ -1,193 +1,174 @@
# installing gitolite # gitolite installatation
[Update 2009-11-18: easy install now works from msysgit also!]
Gitolite is somewhat unusual as far as "server" software goes -- every userid
on the server is a potential "gitolite host".
This document tells you how to install gitolite. After the install is done,
you may want to see [doc/2-admin.mkd][admin] for adding users, repos, etc.
**Please note** that gitolite depends heavily on proper ssh setup and pubkey
based access. Sadly, most people don't know ssh as well as they think they
do. To make matters worse, ssh problems in gitolite don't always look like
ssh problems. Please read about [ssh troubleshooting][doc6] if you have *any*
kind of trouble installing gitolite!
[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
In this document: In this document:
* install methods * <a href="#A1">please read this first</a>
* user install * <a href="#A2">important notes</a>
* typical example run * <a href="#A3">conventions used</a>
* advantages over the older install methods * <a href="#A4">requirements</a>
* disadvantages * <a href="#A5">client side</a>
* upgrades * <a href="#A6">server side</a>
* other notes * <a href="#A7">installation and setup</a>
* system install / user setup * <a href="#A8">(package method) directly on the server, using RPM/DEB</a>
* multiple gitolite instances * <a href="#A9">(root method) directly on the server, manually, with root access</a>
* next steps * <a href="#A10">(non-root method) directly on the server, manually, without root access</a>
* appendix A: server and client requirements for user install * <a href="#A11">(from-client method) install from the client to the server</a>
* server * <a href="#A12">special cases -- multiple gitolite instances</a>
* install workstation * <a href="#A13">upgrading</a>
* admin workstation(s) * <a href="#A14">uninstalling</a>
* appendix B: uninstalling gitolite * <a href="#A15">cleaning out a botched install</a>
* appendix C: NOTE TO PACKAGE MAINTAINERS * <a href="#A16">uninstalling gitolite completely</a>
---- ----
### install methods <a name="A1"></a>
There are 2 ways to install gitolite: The **user-install** mode was the ### please read this first
traditional way, and is used when *any* of the following is true:
* you don't have root on your "server" (some types of hosting setups, many <a name="A2"></a>
corporate paranoia setups ;-)
* your server distro does not have gitolite in its package repositories
* your server distro's package repositories have an old version of gitolite
* you want to stay current with the latest gitolite versions
* your server is not Linux (maybe AIX, or Solaris, etc.)
The "user install" section describes this method. #### important notes
The **system-install followed by user-setup** mode is used when you (or Please make sure you understand the following points first.
someone who has root) has installed an RPM or DEB of gitolite and you intend
to use that version. [Update 2010-04-27: there is now a script called
`gl-system-install` that helps you do a system-install if your distribution
does not yet have a package for gitolite; details below].
The "system install / user setup" section describes this method. * gitolite is somewhat unusual as far as "server" software goes -- every
userid on the server is a potential "gitolite host".
---- * gitolite depends **heavily** on ssh pubkey (passwordless) access. Do not
assume you know all about ssh -- most people **don't**. If in doubt, use
a dedicated userid on both client and server for installation and
administration of gitolite.
### user install To make matters worse, ssh problems in gitolite don't always look like ssh
problems. See [doc/6-ssh-troubleshooting.mkd][doc6] for help.
The `gl-easy-install` script makes installing very easy for this case. **This <a name="A3"></a>
script will setup everything on the server, but you have to run it on your
workstation, NOT on the server!**
Assumptions/pre-requisites: #### conventions used
* you have a server to host gitolite We assume the admin user is "sitaram", and his workstation is called "client".
* git is installed on that server (and so is perl) The hosting user is "git", and the server is called "server". Substitute your
* you have a userid on that server values as needed.
* you have ssh-pubkey (**password-less**) login to that userid
* if you have only password access, run `ssh-keygen -t rsa` to create a
new keypair if needed, then run `ssh-copy-id user@host`. If you do
not have `ssh-copy-id`, read doc/3-faq-tips-etc.mkd and look for
`ssh-copy-id` in that file for instructions
* you have a clone or an archive of gitolite somewhere on your workstation
* if you don't have one, just run `git clone git://github.com/sitaramc/gitolite`
* your workstation has bash (even msysgit bash will do)
Once you have all this, just `cd` to that clone and run `src/gl-easy-install` <a name="A4"></a>
and follow the prompts! (Running it without any arguments shows you usage
plus other useful info).
#### typical example run #### requirements
A typical run for me is: <a name="A5"></a>
src/gl-easy-install -q git my.git.server sitaram ##### client side
`-q` stands for "quiet" mode -- very minimal output, no verbose descriptions * git version 1.6.2 or greater
of what it is going to do, and no pauses unless absolutely needed. However, * even msysgit on Windows is fine; please don't ask me for help if
if you're doing this for the first time or you appreciate knowing what it is you're using putty, plink, puttygen, etc., for ssh; I recommend
actually doing, I suggest you skip the `-q`. msysgit for Windows and the openssh that comes with it
* if you're using the "from-client" method of install (see below), the bash
shell is needed
* again, msysgit on Windows is fine
A detailed transcript of an install done using this method can be found in <a name="A6"></a>
[doc/7-install-transcript.mkd][7it].
[7it]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd ##### server side
#### advantages over the older install methods * any Unix system with a posix compatible "sh".
* people using "csh" or derivatives please don't ask me for help -- tell
your admin csh is not posix compatible
* git version 1.6.2 or greater
* can be in a non-PATH location if you are unable to install it
normally; see the `$GIT_PATH` variable in the "rc" file
* perl (but since git requires it anyway, you probably have it)
* openssh or any ssh that can understand the `authorized_keys` file format
* all ssh problems reduced to **just one pre-requisite**: enable ssh pubkey <a name="A7"></a>
(password-less) access to the server from your workstation first
* the script takes care of all the server side work
* when done:
* you get two different pubkeys (the original one for command line
access as before, plus a new one, created by the script, for gitolite
access)
* you can admin gitolite by commit+push a "gitolite-admin" repo, just
like gitosis (i.e., full "push to admin" power!)
#### disadvantages ### installation and setup
* need a recent bash <a name="A8"></a>
#### upgrades #### (package method) directly on the server, using RPM/DEB
Upgrading gitolite is easy. * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
Put it in `/tmp/sitaram.pub`.
To upgrade, pull the latest "master" (or other) branch in your gitolite repo * (U) on the server, as root, do the install (urpmi, yum, apt-get, etc.).
clone, then run the same exact command you ran to do the install, except you
can leave out the last argument.
And you might want to add a `-q` to speed things up :-) * on the server, "su - git", then as "git" user, run `gl-setup
/tmp/sitaram.pub`.
Note that this only upgrades the software. Unlike earlier versions, it does * on the client, run `cd; git clone git@server:gitolite-admin`
**not** touch the `conf/gitolite.conf` file or the contents of `keydir` in any
way. I decided that it is not possible to **safely** let an upgrade do
something meaningful with them -- fiddling with existing config files (as
opposed to merely creating one which did not exist) is best left to a human.
#### other notes <a name="A9"></a>
* if you run `src/gl-easy-install` without the `-q` option, you will be #### (root method) directly on the server, manually, with root access
given a chance to edit `~/.gitolite.rc`. You can change any options (such
as paths, for instance), but be sure to keep the perl syntax -- you
*don't* have to know perl to do so, it's fairly easy to guess in this
limited case.
---- * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
Put it in `/tmp/sitaram.pub`.
### system install / user setup * (U) on the server, as root, do the following:
(Note: other than getting a public key from the admin's workstation, cd $HOME
everything in this mode of install happens on the server). git clone git://github.com/sitaramc/gitolite gitolite-source
cd gitolite-source
mkdir -p /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
In this mode, the software is first installed system-wide, then the user runs * on the server, "su - git", then as "git" user, run `gl-setup
a command to set up the hosting, supplying a public key. /tmp/sitaram.pub`.
The root user can **install the software system-wide**, using either a package * on the client, run `cd; git clone git@server:gitolite-admin`
(rpm, deb, etc.), or by using the `gl-system-install` script. (Run the script
without any arguments for a brief usage message. If that's not clear enough,
read Appendix C below for details.)
A normal user can then **set up the hosting** by running a command like this: <a name="A10"></a>
gl-setup adminname.pub #### (non-root method) directly on the server, manually, without root access
where adminname.pub is a copy of a public key from that user's workstation. WARNING: if you use this method you'd better know enough about ssh to be able
to keep your keys straight, and you'd also better have password access to the
server so that if you screw up the keys you can still get on, or be able to
"su - git" from some other user on the server.
The first time this is run, it will create a "gitolite-admin" repo and * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
populate it with the right configuration for whoever has the corresponding Put it in `/tmp/sitaram.pub`.
private key to clone and push it. In other words, that person is the
administrator for this particular gitolite instance.
If your system administrator upgrades gitolite itself, things will usually * (U) on the server, as "git", do the following:
just work without any change; you should not normally have to do anything
special. However, some new features may require additional settings in your
`~/.gitolite.rc` file.
Finally, in the rare case that you managed to lose your keys to the admin repo cd $HOME
and want to supply a new pubkey, you can use this command to replace any such git clone git://github.com/sitaramc/gitolite gitolite-source
key. Could be useful in an emergency -- just get your new "yourname.pub" to cd gitolite-source
the server and run the same command as above. mkdir -p $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
**IMPORTANT**: there are two variables in the `~/.gitolite.rc` file: * on the server, still as "git", run `gl-setup /tmp/sitaram.pub`.
`$GL_PACKAGE_CONF` and `$GL_PACKAGE_HOOKS`. If you remove or change either of
them, expect trouble :-)
#### multiple gitolite instances * if `$HOME/bin` is not on the default PATH, fiddle with your `.bashrc` or
`.bash_profile` files and add it somehow. You can also try adding
`$GIT_PATH = "$ENV{HOME}/bin";` to `~/.gitolite.rc` on the server.
With this mode of install, it's trivial to create multiple gitolite instances * on the client, run `cd; git clone git@server:gitolite-admin`
(say one for each department, on some mega company-wide server). You can even
do this without giving shell access to the admins. Here's an example with <a name="A11"></a>
just two "departments", and their admins Alice and Bob:
#### (from-client method) install from the client to the server
This used to be the most common install method for a long time, and it is
still the one I use for most of my testing. The **main advantage** of this
method is that it **forces you** to solve the ssh pubkey problem **before**
attempting to install. Sadly, it also forces the admin to use a **different**
URL for gitolite repos than normal users, which seems to confuse a heck of a
lot of people who don't read the prominently displayed messages and/or the
documentation.
This method is verbosely documented in [doc/7-install-transcript.mkd][doc7],
including *outputs* of the commands concerned.
<a name="A12"></a>
### special cases -- multiple gitolite instances
With the first two methods (package or root methods) of installation, it's
trivial to create multiple gitolite instances (say one for each department, on
some mega company-wide server). You can even do this without giving shell
access to the admins. Here's an example with just two "departments", and
their admins Alice and Bob:
* create userids `webbrowser_repos` and `webserver_repos` * create userids `webbrowser_repos` and `webserver_repos`
* ask Alice and Bob for their pubkeys; copy them to the respective home * ask Alice and Bob for their pubkeys; copy them to the respective home
@ -204,195 +185,52 @@ to have a command line on the server, so don't give them the passwords if you
don't need to -- the pubkey will allow them to be gitolite admins on their don't need to -- the pubkey will allow them to be gitolite admins on their
domain, and that's quite enough for normal operations. domain, and that's quite enough for normal operations.
---- <a name="A13"></a>
### next steps ### upgrading
If you installed it using "gl-easy-install", the last message produced by that Upgrading gitolite is easy. In each method above, just re-do the step that is
script should tell you how to add users, repos, etc. In any case, you will marked "(U)". Also, if you're using either of the two methods that use the
find more details in [doc/2-admin.mkd][admin]. `src/gl-system-install` command, please make sure you give it the same
arguments!
Also, remember that some new features may require additional settings in your
`~/.gitolite.rc` file.
<a name="A14"></a>
### uninstalling
<a name="A15"></a>
#### cleaning out a botched install
When people have trouble installing gitolite, they often try to change a bunch
of things manually on the server. This usually makes things worse ;-) so
here's how to clean the slate.
* client-side
* edit `~/.ssh/config` and delete the paragraph starting with `host
gitolite`, if present.
* remove `~/gitolite-admin`
* server-side
* edit `~/.ssh/authorized_keys` and delete all lines between `# gitolite
start` and `# gitolite end` inclusive.
* remove `~/.gitolite`, `~/.gitolite.rc` and
`~/repositories/gitolite-admin.git`
<a name="A16"></a>
#### uninstalling gitolite completely
There's some duplication between this and the previous section, but
uninstalling gitolite is described in great detail in
[doc/9-uninstall.mkd][doc9unin]
---- ----
<a name="server_reqs"></a> [doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd
[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd
### appendix A: server and client requirements for user install
There are 3 machines *potentially* involved in installing and administering
gitolite.
#### server
This is where gitolite is eventually installed. You need a *normal* userid
(typically "git" but can be anything) on this machine; root access is *not*
needed, but it has to be some sort of Unix (not Windows).
You need the following software on it:
* git
* can be in a non-PATH location if you are unable to install it
normally; see the `$GIT_PATH` variable in the "rc" file
* perl
* default install is fine; no special modules are needed
* (a normal install of git also requires/installs perl, so you probably
have it already)
* openssh server
* (I guess any ssh server that can understand the `authorized_keys` file
format should work)
#### install workstation
Installing or upgrading the gitolite software itself is best done by running
the easy-install program from a gitolite clone.
This script is heavily dependent on bash, so you need a machine with a bash
shell. Even the bash that comes with msysgit is fine, if you don't have a
Linux box handy.
If you have neither Linux nor Windows+msysgit, you still have a few
alternatives:
* use a different userid on the same server (assuming it has bash)
* use the same userid on the same server (same assumption)
* manually simulate the script directly on the server (doable, but tedious)
#### admin workstation(s)
When you install gitolite, it creates a repository called "gitolite-admin" and
gives you permissions on it.
Administering gitolite (adding repos/users, assigning permissions, etc) is
done by cloning this repo, making changes to a file called
`conf/gitolite.conf`, adding users' pubkeys to `keydir/`, and pushing the
changes back to the server.
Which means all this can be done from *any* machine. You'll normally do it
from the same machine you used to install gitolite, but it doesn't have to be
the same one, as long as your pubkey has been added and permissions given to
allow you to push to the gitolite-admin repo.
<a name="uninstall"></a>
### appendix B: uninstalling gitolite
Sometimes you might find gitolite is overkill -- you have only one user
(yourself) pushing maybe. Or maybe gitolite is just not enough -- you want a
web-based front end that users can use to manage their keys themselves, etc.,
in which case you'd probably switch to [github][g1], [girocco][g2],
[indefero][g3] or [gitorious][g4]. [Gerrit][g5] is quite nice too, if you
want collaborative code review there's nothing like it. Either way, you'd
like to uninstall gitolite.
[g1]: http://github.com
[g2]: http://repo.or.cz/w/girocco.git
[g3]: http://www.indefero.net/
[g4]: http://gitorious.com/
[g5]: http://code.google.com/p/gerrit/
Uninstalling gitolite is fairly easy, although it is manual. (We'll assume
`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
not, adjust accordingly):
**server side tasks**
* edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
gitolite end` markers and all the lines between them. This will prevent
any of your users from attempting a push while you are doing this.
If you are the only user, and/or *need* one or more of those keys to
continue to access this account (like if one of them is your laptop or
your home desktop etc.) then instead of deleting the line you can just
delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
* Now remove (or move aside or rename to something else if you're paranoid)
the following files and directories.
~/.gitolite
~/.gitolite.rc
~/repositories/gitolite-admin.git
* You can remove all of `~/repositories` if you have not really started
using gitolite properly yet; that's your choice.
If you *do* need to preserve the other repos and continue to use them,
remove all the `update` hooks that git installs on each repository. The
easiest way is:
find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
but you can do it manually if you want to be careful.
**client side tasks**
* Any remote users that still have access must update their clone's remote
URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
actual path used, in order for the remote to still work. This is because
you'll now be accessing it through plain ssh, which means you have to give
it the full path.
* Finally, you as the gitolite admin will probably have a host stanza for
"gitolite" in your *client*'s `~/.ssh/config`. Find and delete lines that
look like this:
host gitolite
user git
hostname your.server
port 22
identityfile ~/.ssh/your-gitolite-admin-username
### appendix C: NOTE TO PACKAGE MAINTAINERS
Here's how you'd package gitolite. In the following description, location "X"
can be, say, `/usr/share/gitolite/conf` or some such, and similarly location
"Y" can be perhaps `/usr/share/gitolite/hooks`. It's upto your distro
policies where they are.
**Step 1**: Clone the gitolite repo and run the make command inside the clone
git clone git://github.com/sitaramc/gitolite.git
cd gitolite
make pu.tar # or "make master.tar" or "make v1.2.tar" etc
Then you explode the tar file in some temporary location.
*Alternatively, you can `git checkout` the tag or branch you want, and run
this command in the clone directly*:
git describe --tags --long > conf/VERSION
**Step 2**: Now make the following changes (no trailing slashes in the
location values please):
* `src/gl-setup` should have the following line:
GL_PACKAGE_CONF="X"
* `conf/example.gitolite.rc` should have the following lines:
$GL_PACKAGE_CONF="X";
$GL_PACKAGE_HOOKS="Y";
* delete `src/gl-easy-install`; that script is meant for a totally different
mode of installation and does *not* play well in this mode :-)
**Step 3**: Move (or arrange to move) the files to their proper locations as
given below:
* everything in "src" goes somewhere on the PATH
* everything in "conf" goes to location "X"
* everything in "hooks" goes to location "Y"
**Step 4**: There is no step 4. Unless you count telling your users to run
`gl-setup` as a step :)
On the initial install (urpmi, yum install, or apt-get install), you could
also choose to setup a userid called "gitolite", and run "gl-setup" as that
user; however I do not know how you would come up with the initial pubkey that
is needed. Anyway, the point is that the "gitolite" user is no more special
than any other in terms of hosting gitolite. Any user can host gitolite on
his userid by just running "gl-setup".
When you upgrade, just overwrite all the files; it'll all just work. In fact,
other than the initial "gl-setup" run, the only time a gitolite hosting user
has to actually do anything is to edit their own `~/.gitolite.rc` file if they
want to enable or disable specific features.

64
doc/2-admin.mkd
View file

@ -5,37 +5,39 @@
In this document: In this document:
* administer * <a href="#A1">please read this first</a>
* adding users and repos * <a href="#A2">adding users and repos</a>
* moving pre-existing repos into gitolite * <a href="#A3">other features</a>
* specifying gitweb and daemon access * <a href="#A4">moving pre-existing repos into gitolite</a>
* custom hooks * <a href="#A5">specifying gitweb and daemon access</a>
* hook chaining * <a href="#A6">custom hooks</a>
* custom git config * <a href="#A7">hook chaining</a>
* <a href="#A8">custom git config</a>
### administer ----
First of all, ***do NOT add new repos manually***, unless you know how to add <a name="A1"></a>
the required hook as well. Without the hook, branch-level access control will
### please read this first
* ***do NOT add new repos manually***, unless you know how to add the
required hook as well. Without the hook, branch-level access control will
not work for that repo, which sorta defeats the idea of using gitolite :-) not work for that repo, which sorta defeats the idea of using gitolite :-)
Most normal (day-to-day) gitolite admin work is done by cloning the * most normal (day-to-day) gitolite admin work is done by cloning the
gitolite-admin repo from the server to your workstation, making changes to the gitolite-admin repo from the server to your workstation, making changes to
clone, and pushing those changes back. the clone, and pushing those changes back. The installation steps in
[doc/0-INSTALL.mkd][doc0] include the steps to do this clone if needed.
If you installed using "gl-easy-install", that script would have already tried
to clone the repo to your `$HOME`. Otherwise clone it yourself to any
convenient location you like.
Once you've cloned it, you're ready to add users and repos. Once you've cloned it, you're ready to add users and repos.
#### adding users and repos <a name="A2"></a>
### adding users and repos
* ask each user who will get access to send you a public key. See other * ask each user who will get access to send you a public key. See other
sources (for example [here][genpub]) for how to do this sources (for example [here][genpub]) for how to do this
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
* rename each public key according to the user's name, with a `.pub` * rename each public key according to the user's name, with a `.pub`
extension, like `sitaram.pub` or `john-smith.pub`. You can also use extension, like `sitaram.pub` or `john-smith.pub`. You can also use
periods and underscores periods and underscores
@ -48,7 +50,15 @@ Once you've cloned it, you're ready to add users and repos.
and give them permissions as required. The users names should be exactly and give them permissions as required. The users names should be exactly
the same as their keyfile names, but without the `.pub` extension the same as their keyfile names, but without the `.pub` extension
* when done, commit your changes and push * when done, commit your changes and push. Any new repos you specified will
automatically be created (empty, but clonable) and users' access will be
updated as needed.
<a name="A3"></a>
### other features
<a name="A4"></a>
#### moving pre-existing repos into gitolite #### moving pre-existing repos into gitolite
@ -69,6 +79,8 @@ gitolite:
`conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit, `conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit,
push. push.
<a name="A5"></a>
#### specifying gitweb and daemon access #### specifying gitweb and daemon access
This is a feature that I personally do not use (corporate environments don't This is a feature that I personally do not use (corporate environments don't
@ -105,6 +117,8 @@ The "compile" script will keep these files consistent with the config settings
-- this includes removing such settings/files if you remove "read" permissions -- this includes removing such settings/files if you remove "read" permissions
for the special usernames or remove the description line. for the special usernames or remove the description line.
<a name="A6"></a>
#### custom hooks #### custom hooks
You can supply your own, custom, hook scripts if you wish. Just put a You can supply your own, custom, hook scripts if you wish. Just put a
@ -122,6 +136,8 @@ implements all the branch-level permissions in gitolite. If you fiddle with
the hooks directory, please make sure you do not mess with this file the hooks directory, please make sure you do not mess with this file
accidentally, or all your fancy per-branch permissions will stop working.** accidentally, or all your fancy per-branch permissions will stop working.**
<a name="A7"></a>
#### hook chaining #### hook chaining
Gitolite basically takes over the update hook for all repos, but some setups Gitolite basically takes over the update hook for all repos, but some setups
@ -143,6 +159,8 @@ Finally, these names (`update.secondary` and `post-update.secondary`) are
merely the defaults. You can change them to anything you want; look in merely the defaults. You can change them to anything you want; look in
conf/example.gitolite.rc for details. conf/example.gitolite.rc for details.
<a name="A8"></a>
#### custom git config #### custom git config
The custom hooks feature is a blunt instrument -- all repos get the hook you The custom hooks feature is a blunt instrument -- all repos get the hook you
@ -164,3 +182,7 @@ basic forms of the "git config" command:
It does not (currently) support other options like `--add`, the `value_regex`, It does not (currently) support other options like `--add`, the `value_regex`,
etc. etc.
[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key

240
doc/3-faq-tips-etc.mkd
View file

@ -2,43 +2,46 @@
In this document: In this document:
* common errors and mistakes * <a href="#A1">common errors and mistakes</a>
* git version dependency * <a href="#A2">git version dependency</a>
* other errors, warnings, notes... * <a href="#A3">other errors, warnings, notes...</a>
* ssh-copy-id * <a href="#A4">cloning an empty repo</a>
* cloning an empty repo * <a href="#A5">`@all` syntax for repos</a>
* `@all` syntax for repos * <a href="#A6">umask setting</a>
* umask setting * <a href="#A7">getting a tar file from a clone</a>
* getting a tar file from a clone * <a href="#A8">features</a>
* features * <a href="#A9">syntax and normal usage</a>
* syntax and normal usage * <a href="#A10">simpler syntax</a>
* simpler syntax * <a href="#A11">one user, many keys</a>
* one user, many keys * <a href="#A12">security, access control, and auditing</a>
* security, access control, and auditing * <a href="#A13">two levels of access rights checking</a>
* two levels of access rights checking * <a href="#A14">better logging</a>
* better logging * <a href="#A15">"exclude" (or "deny") rules</a>
* "exclude" (or "deny") rules * <a href="#A16">separating delete and rewind rights</a>
* separating delete and rewind rights * <a href="#A17">file/dir NAME based restrictions</a>
* file/dir NAME based restrictions * <a href="#A18">delegating parts of the config file</a>
* delegating parts of the config file * <a href="#A19">convenience features</a>
* convenience features * <a href="#A20">what repos do I have access to?</a>
* what repos do I have access to? * <a href="#A21">including config lines from other files</a>
* error checking the config file * <a href="#A22">support for git installed outside default PATH</a>
* including config lines from other files * <a href="#A23">"personal" branches</a>
* support for git installed outside default PATH * <a href="#A24">custom hooks and custom git config</a>
* "personal" branches * <a href="#A25">helping with gitweb</a>
* custom hooks and custom git config * <a href="#A26">easier to specify gitweb "description" and gitweb/daemon access</a>
* helping with gitweb * <a href="#A27">easier to link gitweb authorisation with gitolite</a>
* easier to specify gitweb "description" and gitweb/daemon access * <a href="#A28">advanced features</a>
* easier to link gitweb authorisation with gitolite * <a href="#A29">repos named with wildcards</a>
* advanced features * <a href="#A30">admin defined commands</a>
* repos named with wildcards * <a href="#A31">access control for external commands</a>
* admin defined commands * <a href="#A32">svnserve</a>
* access control for external commands * <a href="#A33">design choices</a>
* design choices * <a href="#A34">keeping the parser and the access control separate</a>
* keeping the parser and the access control separate
## common errors and mistakes ----
<a name="A1"></a>
### common errors and mistakes
* adding `repositories/` at the start of the repo name in the `git clone`. * adding `repositories/` at the start of the repo name in the `git clone`.
This error is typically made by the *admin* himself -- because he knows This error is typically made by the *admin* himself -- because he knows
@ -60,36 +63,19 @@ In this document:
Please see doc/6-ssh-troubleshooting.mkd for what all this means. Please see doc/6-ssh-troubleshooting.mkd for what all this means.
## git version dependency <a name="A2"></a>
### git version dependency
Gitolite (on the server) now refuses to run if git is not at least 1.6.2. Gitolite (on the server) now refuses to run if git is not at least 1.6.2.
## other errors, warnings, notes... <a name="A3"></a>
### ssh-copy-id ### other errors, warnings, notes...
don't have `ssh-copy-id`? This is broadly what that command does, if you want <a name="A4"></a>
to replicate it manually. The input is your pubkey, typically
`~/.ssh/id_rsa.pub` from your client/workstation.
* it copies it to the server as some file #### cloning an empty repo
* it appends that file to `~/.ssh/authorized_keys` on the server
(creating it if it doesn't already exist)
* it then makes sure that all these files/directories have go-w perms
set (assuming user is "git"):
/home/git/.ssh/authorized_keys
/home/git/.ssh
/home/git
[Actually, `sshd` requires that even directories *above* `~` (`/`, `/home`,
typically) also must be `go-w`, but that needs root. And typically
they're already set that way anyway. (Or if they're not, you've got
bigger problems than gitolite install not working!)]
### cloning an empty repo
Cloning an empty repo is only possible with clients greater than 1.6.2. So at Cloning an empty repo is only possible with clients greater than 1.6.2. So at
least one of your clients needs to have a recent git. Once at least one least one of your clients needs to have a recent git. Once at least one
@ -100,7 +86,9 @@ end hung up unexpectedly`. However, you can ignore this, since it doesn't
seem to hurt anything. [Update 2009-09-14; this has been fixed in git seem to hurt anything. [Update 2009-09-14; this has been fixed in git
1.6.4.3] 1.6.4.3]
### `@all` syntax for repos <a name="A5"></a>
#### `@all` syntax for repos
There *is* a way to use the `@all` syntax for repos also, as described in There *is* a way to use the `@all` syntax for repos also, as described in
`conf/example.conf`. However, there are a couple of minor cautions: `conf/example.conf`. However, there are a couple of minor cautions:
@ -110,12 +98,16 @@ There *is* a way to use the `@all` syntax for repos also, as described in
access, we do not support this. access, we do not support this.
* don't try giving `@all` users some permission for `@all` repos * don't try giving `@all` users some permission for `@all` repos
### umask setting <a name="A6"></a>
#### umask setting
Gitweb not able to read your repos? You can change the umask for newly Gitweb not able to read your repos? You can change the umask for newly
created repos to something more relaxed -- see the `~/.gitolite.rc` file created repos to something more relaxed -- see the `~/.gitolite.rc` file
## getting a tar file from a clone <a name="A7"></a>
### getting a tar file from a clone
You can clone the repo from github or indefero, then execute a make command to You can clone the repo from github or indefero, then execute a make command to
extract a tar file of the branch you want. Please use the make command, not a extract a tar file of the branch you want. Please use the make command, not a
@ -131,17 +123,23 @@ plain "git archive", because the Makefile adds a file called
<a name="features"></a> <a name="features"></a>
## features <a name="A8"></a>
### features
Apart from the big ones listed in the top level README, and subjective ones Apart from the big ones listed in the top level README, and subjective ones
like "better config file format", gitolite has evolved to have many useful like "better config file format", gitolite has evolved to have many useful
fearures than the original goal of "gitosis + branch-level access control". features than the original goal of branch-level access control.
### syntax and normal usage <a name="A9"></a>
#### syntax and normal usage
<a name="simpler_syntax"></a> <a name="simpler_syntax"></a>
#### simpler syntax <a name="A10"></a>
##### simpler syntax
The basic syntax is simpler and cleaner but it goes beyond that: **you can The basic syntax is simpler and cleaner but it goes beyond that: **you can
specify access in bits and pieces**, even if they overlap. specify access in bits and pieces**, even if they overlap.
@ -186,7 +184,9 @@ See the "specify gitweb/daemon access" section below for one more example.
<a name="multikeys"></a> <a name="multikeys"></a>
#### one user, many keys <a name="A11"></a>
##### one user, many keys
I have a laptop and a desktop I need to access the server from. I have I have a laptop and a desktop I need to access the server from. I have
different private keys on them, but as far as gitolite is concerned both of different private keys on them, but as far as gitolite is concerned both of
@ -229,16 +229,19 @@ corresponding derived usernames (which is what goes into the
sitaramc@gmail.com@laptop.pub sitaramc@gmail.com sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
sitaramc@gmail.com@desktop.pub sitaramc@gmail.com sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
### security, access control, and auditing <a name="A12"></a>
#### security, access control, and auditing
<a name="two_levels"></a> <a name="two_levels"></a>
#### two levels of access rights checking <a name="A13"></a>
##### two levels of access rights checking
Gitolite has two levels of access checks. The **first check** is what I will Gitolite has two levels of access checks. The **first check** is what I will
call the **pre-git** level (this is the only check that gitosis has). At this call the **pre-git** level. At this stage, the `gl-auth-command` has been
stage, the `gl-auth-command` has been invoked by `sshd`, and it knows just invoked by `sshd`, and it knows just three things:
three things:
* who, * who,
* what repository, and * what repository, and
@ -268,7 +271,9 @@ any of the refexes match, the push succeeds. If none of them match, it fails.
Gitolite also allows "exclude" or "deny" rules. See later in this document Gitolite also allows "exclude" or "deny" rules. See later in this document
for details. for details.
#### better logging <a name="A14"></a>
##### better logging
If you have been too liberal with the permission to rewind, it has built-in If you have been too liberal with the permission to rewind, it has built-in
logging as an emergency fallback if someone goes too far, or for audit logging as an emergency fallback if someone goes too far, or for audit
@ -294,7 +299,9 @@ The other parts of the log line are the name of the repo, the refname being
updated, the user updating it, and the refex pattern (from the config file) updated, the user updating it, and the refex pattern (from the config file)
that matched, in case you need to debug the config file itself. that matched, in case you need to debug the config file itself.
#### "exclude" (or "deny") rules <a name="A15"></a>
##### "exclude" (or "deny") rules
Here is an illustrative explanation of "deny" rules. However, please be sure Here is an illustrative explanation of "deny" rules. However, please be sure
to read the "DENY/EXCLUDE RULES" section in `conf/example.conf` for important to read the "DENY/EXCLUDE RULES" section in `conf/example.conf` for important
@ -343,7 +350,9 @@ And here's how it works:
before the third one, and it has a `-` as the permission, so the push before the third one, and it has a `-` as the permission, so the push
fails fails
#### separating delete and rewind rights <a name="A16"></a>
##### separating delete and rewind rights
Since the beginning, `RW+` meant being able to rewind *or* delete a ref. My Since the beginning, `RW+` meant being able to rewind *or* delete a ref. My
stand is that these two are fairly similar, and infact a rewind is almost the stand is that these two are fairly similar, and infact a rewind is almost the
@ -380,7 +389,9 @@ message when you push, a non-existant user.
[sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c# [sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c#
#### file/dir NAME based restrictions <a name="A17"></a>
##### file/dir NAME based restrictions
In addition to branch-name based restrictions, gitolite also allows you to In addition to branch-name based restrictions, gitolite also allows you to
restrict what files or directories can be involved in changes being pushed. restrict what files or directories can be involved in changes being pushed.
@ -389,18 +400,24 @@ changed, treating each filename as a "ref" to be matched.
Please see `conf/example.conf` for syntax and examples. Please see `conf/example.conf` for syntax and examples.
#### delegating parts of the config file <a name="A18"></a>
##### delegating parts of the config file
You can now split up the config file and delegate the authority to specify You can now split up the config file and delegate the authority to specify
access control for their own pieces. See access control for their own pieces. See
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd) [doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
for details. for details.
### convenience features <a name="A19"></a>
#### convenience features
<a name="myrights"></a> <a name="myrights"></a>
#### what repos do I have access to? <a name="A20"></a>
##### what repos do I have access to?
Sometimes there are too many repos, maybe even named similarly, or with the Sometimes there are too many repos, maybe even named similarly, or with the
potential for typos, confusion about hyphens/underscores or upper/lower case, potential for typos, confusion about hyphens/underscores or upper/lower case,
@ -431,20 +448,15 @@ administrator can also say things like:
to get this info for other user(s). to get this info for other user(s).
#### error checking the config file <a name="A21"></a>
gitosis does not do any. I just found out that if you mis-spell `members` as ##### including config lines from other files
`member`, gitosis will silently ignore it, and leave you wondering why access
was denied.
Gitolite "compiles" the config file first and keyword typos *are* caught so
you know right away.
#### including config lines from other files
See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`. See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`.
#### support for git installed outside default PATH <a name="A22"></a>
##### support for git installed outside default PATH
The normal solution is to add to the system default PATH somehow, either by The normal solution is to add to the system default PATH somehow, either by
munging `/etc/profile` or by enabling `PermitUserEnvironment` in munging `/etc/profile` or by enabling `PermitUserEnvironment` in
@ -476,7 +488,9 @@ the full PATH in the rc file, like so:
$ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}"; $ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
#### "personal" branches <a name="A23"></a>
##### "personal" branches
"personal" branches are great for corporate environments, where "personal" branches are great for corporate environments, where
unauthenticated pull/clone is a no-no. Since a dev workstation cannot do unauthenticated pull/clone is a no-no. Since a dev workstation cannot do
@ -498,7 +512,9 @@ important thing is that the "branch" name should contain `/USER/` (including
the slashes). At runtime this will match whoever is the current user. Access the slashes). At runtime this will match whoever is the current user. Access
is still determined by the right hand side of course. is still determined by the right hand side of course.
#### custom hooks and custom git config <a name="A24"></a>
##### custom hooks and custom git config
You can specify hooks that you want to propagate to all repos, as well as You can specify hooks that you want to propagate to all repos, as well as
per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and
@ -506,13 +522,17 @@ per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and
<a name="gitweb"></a> <a name="gitweb"></a>
### helping with gitweb <a name="A25"></a>
#### helping with gitweb
Although gitweb is a completely separate program, gitolite can do quite a Although gitweb is a completely separate program, gitolite can do quite a
lot to help you manage gitweb access as well; once the initial setup is lot to help you manage gitweb access as well; once the initial setup is
complete, you can do it all from within the gitolite config file! complete, you can do it all from within the gitolite config file!
#### easier to specify gitweb "description" and gitweb/daemon access <a name="A26"></a>
##### easier to specify gitweb "description" and gitweb/daemon access
To enable access to a repo via gitweb *and* create a "description" for it to To enable access to a repo via gitweb *and* create a "description" for it to
show up on the webpage, just add a line like this, anywhere in the config show up on the webpage, just add a line like this, anywhere in the config
@ -561,7 +581,9 @@ Here's an example, using really short reponames because I'm lazy:
<a name="gitwebauth"></a> <a name="gitwebauth"></a>
#### easier to link gitweb authorisation with gitolite <a name="A27"></a>
##### easier to link gitweb authorisation with gitolite
Over and above whether a repo is even *shown* by gitweb, you may want to Over and above whether a repo is even *shown* by gitweb, you may want to
further restrict people, allowing them to view *only* those repos for which further restrict people, allowing them to view *only* those repos for which
@ -595,18 +617,26 @@ Gitweb allows you to specify a subroutine to decide on access. We use that
feature and tie it to gitolite. Configuration example can be found in feature and tie it to gitolite. Configuration example can be found in
`contrib/gitweb/`. `contrib/gitweb/`.
### advanced features <a name="A28"></a>
#### repos named with wildcards #### advanced features
<a name="A29"></a>
##### repos named with wildcards
Please see `doc/4-wildcard-repositories.mkd` for all the details. Please see `doc/4-wildcard-repositories.mkd` for all the details.
#### admin defined commands <a name="A30"></a>
##### admin defined commands
This requires the wildcards feature to be enabled, but is then an extremely This requires the wildcards feature to be enabled, but is then an extremely
powerful feature. See `doc/admin-defined-commands.mkd`. powerful feature. See `doc/admin-defined-commands.mkd`.
#### access control for external commands <a name="A31"></a>
##### access control for external commands
Gitolite now has a mechanism for allowing access control for arbitrary Gitolite now has a mechanism for allowing access control for arbitrary
external commands, as long as they are invoked via ssh and present a external commands, as long as they are invoked via ssh and present a
@ -630,7 +660,9 @@ Commands implemented so far are:
<a name="svnserve"></a> <a name="svnserve"></a>
##### svnserve <a name="A32"></a>
###### svnserve
If you are transitioning from SVN to gitolite, and have a lot of users using If you are transitioning from SVN to gitolite, and have a lot of users using
public-key authentication with SVN, this feature may be useful to you. Once public-key authentication with SVN, this feature may be useful to you. Once
@ -640,9 +672,13 @@ system. Assuming you installed gitolite to the same user as the one you used
for SVN, SVN connectivity will be retained, and users will be able to use for SVN, SVN connectivity will be retained, and users will be able to use
both SVN and git using the same SSH configuration. both SVN and git using the same SSH configuration.
## design choices <a name="A33"></a>
### keeping the parser and the access control separate ### design choices
<a name="A34"></a>
#### keeping the parser and the access control separate
There are two programs concerned with access control: There are two programs concerned with access control:

46
doc/4-wildcard-repositories.mkd
View file

@ -19,34 +19,42 @@ workarounds I may not have the time to code it right away.
In this document: In this document:
* rc file setting required * <a href="#A1">rc file setting required</a>
* wildcard repos * <a href="#A2">Wildcard repos</a>
* wildcard repos with creator name in them * <a href="#A3">Wildcard repos with creator name in them</a>
* wildcard repos without creator name in them * <a href="#A4">Wildcard repos without creator name in them</a>
* side-note: line-anchored regexes * <a href="#A5">Side-note: Line-anchored regexes</a>
* contrast with refexes * <a href="#A6">Contrast with refexes</a>
* handing out rights to wildcard-matched repos * <a href="#A7">Handing out rights to wildcard-matched repos</a>
* setting a gitweb description for a wildcard-matched repo * <a href="#A8">setting a gitweb description for a wildcard-matched repo</a>
* reporting * <a href="#A9">reporting</a>
* other issues and discussion * <a href="#A10">other issues and discussion</a>
* how it actually works * <a href="#A11">how it actually works</a>
----
This document is mostly "by example". This document is mostly "by example".
---- ----
<a name="A1"></a>
### rc file setting required ### rc file setting required
This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc` This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
on the server. Please search for that variable and see comments around it in on the server. Please search for that variable and see comments around it in
`conf/example.gitolite.rc` for more information on this. `conf/example.gitolite.rc` for more information on this.
<a name="A2"></a>
### Wildcard repos ### Wildcard repos
Which of these alternatives you choose depends on your needs, and the social Which of these alternatives you choose depends on your needs, and the social
aspects of your environment. The first one is a little more rigid, making it aspects of your environment. The first one is a little more rigid, making it
harder to make mistakes, and the second is more flexible and trusting. harder to make mistakes, and the second is more flexible and trusting.
<a name="A3"></a>
#### Wildcard repos with creator name in them #### Wildcard repos with creator name in them
Here's an example snippet: Here's an example snippet:
@ -71,6 +79,8 @@ new repo, as user "u4" (a student):
Notice the *two* empty repo inits, and the order in which they occur ;-) Notice the *two* empty repo inits, and the order in which they occur ;-)
<a name="A4"></a>
#### Wildcard repos without creator name in them #### Wildcard repos without creator name in them
Here's how the same example would look if you did not want the CREATOR's name Here's how the same example would look if you did not want the CREATOR's name
@ -96,6 +106,8 @@ and have a TA create the repos in advance.
In either case, they could then use the `setperms` feature to specify which In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details. users are "READERS" and which are "WRITERS". See later for details.
<a name="A5"></a>
### Side-note: Line-anchored regexes ### Side-note: Line-anchored regexes
A regex like A regex like
@ -111,6 +123,8 @@ But you may be surprised to find that it does not match even
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters. metacharacters.
<a name="A6"></a>
#### Contrast with refexes #### Contrast with refexes
Just for interest, note that this is in contrast to the refexes for the normal Just for interest, note that this is in contrast to the refexes for the normal
@ -121,6 +135,8 @@ if no one will actually push such a branch! You can anchor both sides if you
really care, by using `master$` instead of `master`, but that is *not* the really care, by using `master$` instead of `master`, but that is *not* the
default for refexes. default for refexes.
<a name="A7"></a>
### Handing out rights to wildcard-matched repos ### Handing out rights to wildcard-matched repos
In the examples above, we saw two special "user" names: READERS and WRITERS. In the examples above, we saw two special "user" names: READERS and WRITERS.
@ -166,11 +182,15 @@ The following points are important:
* whoever you specify as "R" will match the special user READERS. "RW" will * whoever you specify as "R" will match the special user READERS. "RW" will
match WRITERS. match WRITERS.
<a name="A8"></a>
### setting a gitweb description for a wildcard-matched repo ### setting a gitweb description for a wildcard-matched repo
Similar to the getperm/setperm commands, there are the getdesc/setdesc Similar to the getperm/setperm commands, there are the getdesc/setdesc
commands, thanks to Teemu. commands, thanks to Teemu.
<a name="A9"></a>
### reporting ### reporting
Remember the cool stuff you see when you just do `ssh git@server` (grep for Remember the cool stuff you see when you just do `ssh git@server` (grep for
@ -195,6 +215,8 @@ Push the config, then try
ssh gitolite expand ssh gitolite expand
<a name="A10"></a>
### other issues and discussion ### other issues and discussion
* *what if the repo name being pushed matches more than one pattern*? * *what if the repo name being pushed matches more than one pattern*?
@ -215,6 +237,8 @@ Push the config, then try
of the time, it won't be difficult; the fixed prefix will usually be of the time, it won't be difficult; the fixed prefix will usually be
different anyway so there won't be overlaps. different anyway so there won't be overlaps.
<a name="A11"></a>
### how it actually works ### how it actually works
This section tells you what is happening inside gitolite so you can understand This section tells you what is happening inside gitolite so you can understand

21
doc/5-delegation.mkd
View file

@ -2,6 +2,19 @@
[Thanks to jeromeag for forcing me to think through this...] [Thanks to jeromeag for forcing me to think through this...]
----
In this document:
* <a href="#A1">lots of repos, lots of users</a>
* <a href="#A2">splitting up the set of repos into groups</a>
* <a href="#A3">delegating ownership of groups of repos</a>
* <a href="#A4">security/philosophy note</a>
----
<a name="A1"></a>
### lots of repos, lots of users ### lots of repos, lots of users
Gitolite tries to make it easy to manage access to lots of users and repos, Gitolite tries to make it easy to manage access to lots of users and repos,
@ -34,6 +47,8 @@ access control rules for a set of repos they have been given authority for.
It's easier to show how it all works with an example instead of long It's easier to show how it all works with an example instead of long
descriptions. descriptions.
<a name="A2"></a>
### splitting up the set of repos into groups ### splitting up the set of repos into groups
To start with, recall that gitolite allows you to specify **groups** (of users To start with, recall that gitolite allows you to specify **groups** (of users
@ -48,6 +63,8 @@ or repos, same syntax). So the basic idea is that the main config file
# any other config as usual, including access control lines for any of the # any other config as usual, including access control lines for any of the
# above projects or groups # above projects or groups
<a name="A3"></a>
### delegating ownership of groups of repos ### delegating ownership of groups of repos
Once the repos are grouped, give each person charge of one or more groups. Once the repos are grouped, give each person charge of one or more groups.
@ -100,7 +117,9 @@ to the bottom of the main file.
---- ----
### Security/Philosophy note <a name="A4"></a>
### security/philosophy note
The delegation feature is meant only for access control rules, not pubkeys. The delegation feature is meant only for access control rules, not pubkeys.
Adding/removing pubkeys is a much more significant event than changing branch Adding/removing pubkeys is a much more significant event than changing branch

118
doc/6-ssh-troubleshooting.mkd
View file

@ -2,38 +2,44 @@
In this document: In this document:
* the most common problems that an admin will see * <a href="#A1">the most common problems that an admin will see</a>
* basic ssh troubleshooting * <a href="#A2">basic ssh troubleshooting</a>
* passphrases versus passwords * <a href="#A3">passphrases versus passwords</a>
* ssh-agent problems * <a href="#A4">ssh-agent problems</a>
* basic ssh troubleshooting for the main admin * <a href="#A5">basic ssh troubleshooting for the main admin</a>
* basic ssh troubleshooting for a normal user * <a href="#A6">basic ssh troubleshooting for a normal user</a>
* details * <a href="#A7">details</a>
* files on the server * <a href="#A8">files on the server</a>
* files on client * <a href="#A9">files on client</a>
* why two keys on client * <a href="#A10">why two keys on client</a>
* more complex ssh setups * <a href="#A11">some other tips and tricks</a>
* two gitolite servers to manage? * <a href="#A12">two gitolite servers to manage?</a>
* giving shell access to gitolite users * <a href="#A13">giving shell access to gitolite users</a>
* <a href="#A14">losing your admin key</a>
* <a href="#A15">simulating ssh-copy-id</a>
---- ----
This document should help you troubleshoot ssh-related problems in accessing This document should help you troubleshoot ssh-related problems in accessing
gitolite *after* the install has completed successfully. gitolite *after* the install has completed successfully.
In addition, I **strongly** recommend reading [this document][glb] -- it's a In addition, I **strongly** recommend reading
very detailed look at how gitolite uses ssh's features on the server side. [doc/9-gitolite-and-ssh.mkd][doc9gas], which is a very detailed look at how
Most people don't know ssh as well as they *think* they do; even if you don't gitolite uses ssh's features on the server side. Most people don't know ssh
have any problems right now, it's worth skimming over. as well as they *think* they do; even if you don't have any problems right
now, it's worth skimming over.
In addition to both these documents, there's now a program called In addition to both these documents, there's now a program called
`sshkeys-lint` that you can run on your client. Run it without arguments to `sshkeys-lint` that you can run on your client. Run it without arguments to
get help on how to run it and what inputs it needs. get help on how to run it and what inputs it needs.
<a name="A1"></a>
### the most common problems that an admin will see ### the most common problems that an admin will see
Ironically, these problems **only** happen to the person who installed Ironically, these problems **only** happen to the person who installed
gitolite using easy-install, and has **utterly failed** to read/heed the gitolite using easy-install (the "from-client" method in
[doc/0-INSTALL.mkd][doc0]), and has **utterly failed** to read/heed the
message that shows up at the end of running that command. This is because message that shows up at the end of running that command. This is because
only the admin has *two* ssh keys to the server (see "basic ssh only the admin has *two* ssh keys to the server (see "basic ssh
troubleshooting for the main admin" section below for more on this). troubleshooting for the main admin" section below for more on this).
@ -44,7 +50,9 @@ completely**:
* you get `fatal: 'reponame' does not appear to be a git repository`, and * you get `fatal: 'reponame' does not appear to be a git repository`, and
yet you are sure 'reponame' exists, you haven't mis-spelled it, etc. yet you are sure 'reponame' exists, you haven't mis-spelled it, etc.
* you are able to clone repositories but are unable to push changes back. * you are able to clone repositories but are unable to push changes back
(the error complains about the `GL_RC` environment variable not being set,
and the `hooks/update` failing in some way).
Let us recap the message that appears on a successful run of the "easy-install" Let us recap the message that appears on a successful run of the "easy-install"
program; it looks something like this (with suitable values substituted for program; it looks something like this (with suitable values substituted for
@ -77,9 +85,7 @@ the repo and clones ok. But when you push, gitolite's **update hook** kicks
in, and fails to run because you some of the environment variables it is in, and fails to run because you some of the environment variables it is
expecting are not present. expecting are not present.
---- <a name="A2"></a>
<a name="basic"></a>
### basic ssh troubleshooting ### basic ssh troubleshooting
@ -92,6 +98,8 @@ username* of the admin.
Unless specifically mentioned, all these commands are run on the user's or Unless specifically mentioned, all these commands are run on the user's or
admin's workstation, not on the server. admin's workstation, not on the server.
<a name="A3"></a>
#### passphrases versus passwords #### passphrases versus passwords
When you create an ssh keypair, you have the option of protecting it with a When you create an ssh keypair, you have the option of protecting it with a
@ -111,6 +119,8 @@ The second is to use `ssh-agent` (or `keychain`, which in turn uses
`ssh-agent`) or something like that to manage your keys. Other than the next `ssh-agent`) or something like that to manage your keys. Other than the next
section, further discussion of this is out of scope of this document. section, further discussion of this is out of scope of this document.
<a name="A4"></a>
#### ssh-agent problems #### ssh-agent problems
1. Run `ssh-add -l`. If this responds with either "The agent has no 1. Run `ssh-add -l`. If this responds with either "The agent has no
@ -135,6 +145,8 @@ all, ssh will only use those keys. Even if you explicitly specify an unlisted
key using `ssh -i` or an `identityfile` directive in the config file, it won't key using `ssh -i` or an `identityfile` directive in the config file, it won't
use it. use it.
<a name="A5"></a>
#### basic ssh troubleshooting for the main admin #### basic ssh troubleshooting for the main admin
You're the "main admin" if you're trying to access gitolite from the same You're the "main admin" if you're trying to access gitolite from the same
@ -203,6 +215,8 @@ from scratch:
That's a long sequence but it should work. That's a long sequence but it should work.
<a name="A6"></a>
#### basic ssh troubleshooting for a normal user #### basic ssh troubleshooting for a normal user
For a normal user, life is much simpler. They should have only one pubkey, For a normal user, life is much simpler. They should have only one pubkey,
@ -222,10 +236,14 @@ the admin repo, it won't work. For reasons why, see below.
<a name="details"></a> <a name="details"></a>
<a name="A7"></a>
### details ### details
Here's how it all hangs together. Here's how it all hangs together.
<a name="A8"></a>
#### files on the server #### files on the server
* the authkeys file; this contains one line containing the pubkey of each * the authkeys file; this contains one line containing the pubkey of each
@ -256,6 +274,8 @@ Here's how it all hangs together.
argument `sitaram`. This is how gitolite is invoked, (and is told the argument `sitaram`. This is how gitolite is invoked, (and is told the
user logging in is "sitaram"). user logging in is "sitaram").
<a name="A9"></a>
#### files on client #### files on client
* default keypair; used to get shell access to servers. You would have * default keypair; used to get shell access to servers. You would have
@ -326,8 +346,13 @@ Here's how it all hangs together.
<a name="twokeys"></a> <a name="twokeys"></a>
<a name="A10"></a>
#### why two keys on client #### why two keys on client
[This section is only applicable to installs done using the "from-client"
method; see [doc/0-INSTALL.mkd][doc0] for details].
Why do I (the admin) need two **different** keypairs? Why do I (the admin) need two **different** keypairs?
There are two types of access the admin will make to the server: a normal There are two types of access the admin will make to the server: a normal
@ -390,10 +415,11 @@ That should do it.
<a name="complex"></a> <a name="complex"></a>
### more complex ssh setups <a name="A11"></a>
What do you need to know in order to create more complex ssh setups (for ### some other tips and tricks
instance if you have *two* gitolite servers you are administering)?
<a name="A12"></a>
#### two gitolite servers to manage? #### two gitolite servers to manage?
@ -415,9 +441,9 @@ instance if you have *two* gitolite servers you are administering)?
* now access one server's repos as `gitolite:reponame.git` and the other * now access one server's repos as `gitolite:reponame.git` and the other
server's repos as `gitolite2:reponame.git`. server's repos as `gitolite2:reponame.git`.
<a name="shell"></a> <a name="A13"></a>
### giving shell access to gitolite users #### giving shell access to gitolite users
We've managed (thanks to an idea from Jesse Keating) to make it possible for a We've managed (thanks to an idea from Jesse Keating) to make it possible for a
single key to allow both gitolite access *and* shell access. single key to allow both gitolite access *and* shell access.
@ -442,3 +468,41 @@ access would not manage to get himself shell access.
Giving someone shell access requires that you should have shell access in the Giving someone shell access requires that you should have shell access in the
first place, so the simplest way is to enable it from the server side only. first place, so the simplest way is to enable it from the server side only.
<a name="A14"></a>
#### losing your admin key
If you lost the admin key, and need to re-establish ownership of the
gitolite-admin repository with a fresh key, take a look at the
`src/gl-emergency-addkey` program. You will need shell access to the server
of course. The top of the script has useful information on how to use it and
what it needs.
<a name="A15"></a>
#### simulating ssh-copy-id
don't have `ssh-copy-id`? This is broadly what that command does, if you want
to replicate it manually. The input is your pubkey, typically
`~/.ssh/id_rsa.pub` from your client/workstation.
* it copies it to the server as some file
* it appends that file to `~/.ssh/authorized_keys` on the server
(creating it if it doesn't already exist)
* it then makes sure that all these files/directories have go-w perms
set (assuming user is "git"):
/home/git/.ssh/authorized_keys
/home/git/.ssh
/home/git
[Actually, `sshd` requires that even directories *above* `~` (`/`, `/home`,
typically) also must be `go-w`, but that needs root. And typically
they're already set that way anyway. (Or if they're not, you've got
bigger problems than gitolite install not working!)]
[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd

28
doc/7-install-transcript.mkd
View file

@ -15,20 +15,21 @@ Please note that this entire transcript can be summarised as:
...and only that last step is actually gitolite. In fact, the bulk of the ...and only that last step is actually gitolite. In fact, the bulk of the
transcript is **non**-gitolite stuff :) transcript is **non**-gitolite stuff :)
---- **Please also note that this method will setup everything on the server, but
you have to run it on your workstation, NOT on the server!**
### (cleaning out a botched install if needed) In this document:
When people have trouble installing gitolite, they often try to change a bunch * <a href="#A1">create userids on server and client (optional)</a>
of things manually on the server. This usually makes things worse ;-) so if * <a href="#A2">get pubkey access from client to server</a>
you're reading this document as a follow-up to a failed install, please * <a href="#A3">get gitolite source</a>
**first** clean out the botched install (instructions [here][appB]) and * <a href="#A4">install gitolite</a>
**then** continue with this document. * <a href="#A5">examine what you have</a>
[appB]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#uninstall
---- ----
<a name="A1"></a>
### create userids on server and client (optional) ### create userids on server and client (optional)
Client side: add user, give him a password Client side: add user, give him a password
@ -74,6 +75,8 @@ because I'm not showing the actual "vi" session):
---- ----
<a name="A2"></a>
### get pubkey access from client to server ### get pubkey access from client to server
This involves creating a keypair for yourself (using `ssh-keygen`), and This involves creating a keypair for yourself (using `ssh-keygen`), and
@ -123,6 +126,8 @@ Double check to make sure you can log on to `git@server` without a password:
---- ----
<a name="A3"></a>
### get gitolite source ### get gitolite source
sita@sita-lt:~ $ git clone git://github.com/sitaramc/gitolite gitolite-source sita@sita-lt:~ $ git clone git://github.com/sitaramc/gitolite gitolite-source
@ -133,6 +138,8 @@ Double check to make sure you can log on to `git@server` without a password:
Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done. Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done.
Resolving deltas: 100% (756/756), done. Resolving deltas: 100% (756/756), done.
<a name="A4"></a>
### install gitolite ### install gitolite
Note that gitolite is installed from the *client*. The `easy-install` script Note that gitolite is installed from the *client*. The `easy-install` script
@ -145,7 +152,6 @@ install sequence**. </font> Run it without any arguments to see a usage
message. Run it without the `-q` to get a more verbose, pause-at-every-step, message. Run it without the `-q` to get a more verbose, pause-at-every-step,
install mode that allows you to change the defaults etc. install mode that allows you to change the defaults etc.
sita@sita-lt:src $ ./gl-easy-install -q git server sitaram sita@sita-lt:src $ ./gl-easy-install -q git server sitaram
you are upgrading (or installing first-time) to v0.95-38-gb0ce84d you are upgrading (or installing first-time) to v0.95-38-gb0ce84d
setting up keypair... setting up keypair...
@ -203,6 +209,8 @@ install mode that allows you to change the defaults etc.
---- ----
<a name="A5"></a>
### examine what you have ### examine what you have
sita@sita-lt:src $ cd ~/gitolite-admin/ sita@sita-lt:src $ cd ~/gitolite-admin/

155
doc/9-gitolite-and-ssh.mkd Normal file
View file

@ -0,0 +1,155 @@
# how gitolite uses ssh
Here's a secret: ***gitolite uses far more ssh magic than git magic***!
Most people didn't realise this, and even if they did they didn't know ssh
well enough to help themselves. If you don't understand how ssh public key
authentication works, or how the `~/.ssh/authorized_keys` file can be used to
restrict users, etc., you will have endless amounts of trouble getting
gitolite to work, because you'll be attacking the wrong problem.
So please please please understand this before tearing your hair out and
blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
In this document:
* <a href="#A1">ssh basics</a>
* <a href="#A2">how does gitolite use all this ssh magic?</a>
* <a href="#A3">restricting shell access/distinguishing one user from another</a>
* <a href="#A4">restricting branch level actions</a>
----
<a name="A1"></a>
### ssh basics
Let's start with some basics, focusing *only* on the pieces relevant to
`gitolite`. If this is not detailed enough, please use google and learn more
from somewhere, or maybe buy the OReilly ssh book.
* You can login to an ssh server by typing a password, but ssh can also use
***public-private keys*** (also called "key pairs") for authentication.
`gitolite` *requires* you to use this mechanism for your users -- they
cannot log in using passwords. Hopefully by the time you finish reading
this document you will understand why :-)
The way you set this up is you generate a key pair on your workstation,
and give the server the public key. (I need not add that the "private"
key must be, well, kept *private*!)
* **generating a key pair on your workstation** is done by running the
command `ssh-keygen -t rsa`. This produces two files in `~/.ssh`. One is
`id_rsa`; this is the **private** key -- ***never*** let it out of your
machine. The other is `id_rsa.pub`, which is the corresponding public
key. This public key is usually just one long line of text.
* on Windows machines with msysgit installed, you should do this from
within a "git bash" window. The command will report the full path where
the files have been written; make a note of this, and use those files in
any of the description that follows
* **adding your public key to the server**'s `~/.ssh/authorized_keys`
file is how ssh uses pubkeys to authenticate users. Let's say
sita@work.station is trying to log in as git@serv.er. What you have to do
is take the `~/.ssh/id_rsa.pub` file for user sita on work.station and
append its contents (remember it's only one line) to
`~/.ssh/authorized_keys` for user git on serv.er.
The `authorized_keys` file can have multiple public keys (from many
different people) added to it so any of them can log in to git@serv.er.
In the normal case (not gitolite, but your normal everyday shell access),
there's a command that does this, `ssh-copy-id`, which also fixes up
permissions etc., as needed, since sshd is a little picky about allowing
pubkey access if permissions on the server are loose. Or you can do it
manually, as long as you know what you're doing and you're careful not to
erase or overwrite the existing contents of `~/.ssh/authorized_keys` on
the server!
But in the gitolite case, it's different; we'll get to that in a minute.
* **troubleshooting pubkey authentication failures**: if you are unable to
get ssh access to the server after doing all this, you'll have to look
in `/var/log/secure` or `/var/log/auth.log` or some such file on the
server to see what specific error `sshd` is complaining about.
* **restricting users to specific commands** is very important for gitolite.
If you read `man sshd` and look for `authorized_keys file format`, you'll
see a lot of options you can add to the public key line, which restrict
the incoming user in various ways. In particular, note the `command=`
option, which means "regardless of what the incoming user is asking to do,
forcibly run this command instead".
Also note that when there are many public keys (i.e., lines) in the
`authorized_keys` file, each line can have a *different* set of options
and `command=` values.
**This is the backbone of what makes gitolite work; please make sure you
understand this**
<a name="A2"></a>
### how does gitolite use all this ssh magic?
These are two different questions you ought to be having by now:
* how does it distinguish between me and someone else, since we're all
logging in as the same remote user "git"
* how does it restrict what I can do within a repository
<a name="A3"></a>
#### restricting shell access/distinguishing one user from another
The answer to the first question is the `command=` we talked about before. If
you look in the `authorized_keys` file, you'll see entries like this (I chopped
off the ends of course; they're pretty long lines):
command="[path]/gl-auth-command sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t...
command="[path]/gl-auth-command usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
First, it finds out which of the public keys in this file match the incoming
login. That's crypto stuff, and I won't go into it. Once the match has been
found, it will run the command given on that line; e.g., if I logged in, it
would run `[path]/gl-auth-command sitaram`. So the first thing to note is
that such users do not get "shell access", which is good!
Before running the command, however, sshd sets up an environment variable
called `SSH_ORIGINAL_COMMAND` which contains the actual git command that your
workstation sent out. This is the command that *would have run* if you did
not have the `command=` part in the authorised keys file.
When `gl-auth-command` gets control, it looks at the first argument
("sitaram", "usertwo", etc) to determine who you are. It then looks at the
`SSH_ORIGINAL_COMMAND` variable to find out which repository you want to
access, and whether you're reading or writing.
Now is has user, repository, and access requested (read/write), gitolite looks
at its config file, and either allows or rejects the request.
But this cannot differentiate between different branches within a repo; that
has to be done separately.
<a name="A4"></a>
#### restricting branch level actions
[If you look inside the git source tree, there's a file among the "howto"s in
there called `update-hook-example.txt`, which was the inspiration for this
part of gitolite.]
Git allows you to specify many "hooks", which get control as various events
happen -- see `git help hooks` for details. One of those hooks is the
`update` hook, which, if it is present, is invoked just before a branch or a
tag is about to be updated. The hook is passed the name of the branch or tag,
the old SHA1 value, and the new SHA1 value, as arguments. Hooks that are
called *before* an action happens are allowed to prevent that action from
happening y returning an error code.
When gitolite is told to create a new repository (by the admin), it installs
a special update hook. This hook takes all the information presented, looks
at the config file, and decides to allow or reject the update.
And that's basically it.

56
doc/9-packaging.mkd Normal file
View file

@ -0,0 +1,56 @@
# packaging gitolite
Here's how you'd package gitolite. In the following description, location "X"
can be, say, `/usr/share/gitolite/conf` or some such, and similarly location
"Y" can be perhaps `/usr/share/gitolite/hooks`. It's upto your distro
policies where they are.
**Step 1**: Clone the gitolite repo and run the make command inside the clone
git clone git://github.com/sitaramc/gitolite.git
cd gitolite
make pu.tar # or "make master.tar" or "make v1.2.tar" etc
Then you explode the tar file in some temporary location.
*Alternatively, you can `git checkout` the tag or branch you want, and run
this command in the clone directly*:
git describe --tags --long > conf/VERSION
**Step 2**: Now make the following changes (no trailing slashes in the
location values please):
* `src/gl-setup` should have the following line:
GL_PACKAGE_CONF="X"
* `conf/example.gitolite.rc` should have the following lines:
$GL_PACKAGE_CONF="X";
$GL_PACKAGE_HOOKS="Y";
* delete `src/gl-easy-install`; that script is meant for a totally different
mode of installation and does *not* play well in this mode :-)
**Step 3**: Move (or arrange to move) the files to their proper locations as
given below:
* everything in "src" goes somewhere on the PATH
* everything in "conf" goes to location "X"
* everything in "hooks" goes to location "Y"
**Step 4**: There is no step 4. Unless you count telling your users to run
`gl-setup` as a step :)
On the initial install (urpmi, yum install, or apt-get install), you could
also choose to setup a userid called "gitolite", and run "gl-setup" as that
user; however I do not know how you would come up with the initial pubkey that
is needed. Anyway, the point is that the "gitolite" user is no more special
than any other in terms of hosting gitolite. Any user can host gitolite on
his userid by just running "gl-setup".
When you upgrade, just overwrite all the files; it'll all just work. In fact,
other than the initial "gl-setup" run, the only time a gitolite hosting user
has to actually do anything is to edit their own `~/.gitolite.rc` file if they
want to enable or disable specific features.

67
doc/9-uninstall.mkd Normal file
View file

@ -0,0 +1,67 @@
# uninstalling gitolite
Sometimes you might find gitolite is overkill -- you have only one user
(yourself) pushing maybe. Or maybe gitolite is just not enough -- you want a
web-based front end that users can use to manage their keys themselves, etc.,
in which case you'd probably switch to [github][g1], [girocco][g2],
[indefero][g3] or [gitorious][g4]. [Gerrit][g5] is quite nice too, if you
want collaborative code review there's nothing like it. Either way, you'd
like to uninstall gitolite.
[g1]: http://github.com
[g2]: http://repo.or.cz/w/girocco.git
[g3]: http://www.indefero.net/
[g4]: http://gitorious.com/
[g5]: http://code.google.com/p/gerrit/
Uninstalling gitolite is fairly easy, although it is manual. (We'll assume
`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
not, adjust accordingly):
**server side tasks**
* edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
gitolite end` markers and all the lines between them. This will prevent
any of your users from attempting a push while you are doing this.
If you are the only user, and/or *need* one or more of those keys to
continue to access this account (like if one of them is your laptop or
your home desktop etc.) then instead of deleting the line you can just
delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
* Now remove (or move aside or rename to something else if you're paranoid)
the following files and directories.
~/.gitolite
~/.gitolite.rc
~/repositories/gitolite-admin.git
* You can remove all of `~/repositories` if you have not really started
using gitolite properly yet; that's your choice.
If you *do* need to preserve the other repos and continue to use them,
remove all the `update` hooks that git installs on each repository. The
easiest way is:
find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
but you can do it manually if you want to be careful.
**client side tasks**
* Any remote users that still have access must update their clone's remote
URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
actual path used, in order for the remote to still work. This is because
you'll now be accessing it through plain ssh, which means you have to give
it the full path.
* Finally, you as the gitolite admin will probably have a host stanza for
"gitolite" in your *client*'s `~/.ssh/config`. Find and delete lines that
look like this:
host gitolite
user git
hostname your.server
port 22
identityfile ~/.ssh/your-gitolite-admin-username

3
doc/TODO
View file

@ -1,3 +0,0 @@
* make a proper test suite
* change the "rc" file to use "gitconfig" instead...

28
doc/admin-defined-commands.mkd
View file

@ -11,16 +11,18 @@ There may be other such **WARNING** sections below. **Read all of them**.
In this document: In this document:
* background * <a href="#A1">background</a>
* setting it up * <a href="#A2">setting it up</a>
* anatomy of a command * <a href="#A3">anatomy of a command</a>
* example uses and sample commands in contrib * <a href="#A4">example uses and sample commands in contrib</a>
* fork * <a href="#A5">fork</a>
* rmrepo * <a href="#A6">rmrepo</a>
* (bonus) restricted admin * <a href="#A7">(bonus) restricted admin</a>
---- ----
<a name="A1"></a>
### background ### background
Gitolite was named to be short for "gitosis-lite". Someone now wants to turn Gitolite was named to be short for "gitosis-lite". Someone now wants to turn
@ -59,6 +61,8 @@ What we want now is more than that, as you'll see in the examples below. And
I'm sure if you think of more uses you'll send them to me as "contrib" I'm sure if you think of more uses you'll send them to me as "contrib"
entries, right? entries, right?
<a name="A2"></a>
### setting it up ### setting it up
This can only be setup by someone who has shell access to the server. Edit This can only be setup by someone who has shell access to the server. Edit
@ -77,6 +81,8 @@ to inadvertently *hide* some of the "official" commands (like "info",
executable files with those names in this directory. So don't do that -- you executable files with those names in this directory. So don't do that -- you
have been warned!** have been warned!**
<a name="A3"></a>
### anatomy of a command ### anatomy of a command
You can basically do whatever you want in such a command -- go wild! It's You can basically do whatever you want in such a command -- go wild! It's
@ -130,8 +136,12 @@ convenient. See any of the other samples for how to use it.
If you don't like this, roll your own. If you don't like bash, do the eqvt in If you don't like this, roll your own. If you don't like bash, do the eqvt in
your language of choice. your language of choice.
<a name="A4"></a>
### example uses and sample commands in contrib ### example uses and sample commands in contrib
<a name="A5"></a>
#### fork #### fork
A user would use the fork command like this: A user would use the fork command like this:
@ -165,6 +175,8 @@ So now we have an actual command to just create a repo and do nothing else:
`ssh git@server git-init \'reponame\'`. [Yes; those single quotes are `ssh git@server git-init \'reponame\'`. [Yes; those single quotes are
required. Deal with it.] required. Deal with it.]
<a name="A6"></a>
#### rmrepo #### rmrepo
This is one thing that you really could not do before this setup was created. This is one thing that you really could not do before this setup was created.
@ -175,6 +187,8 @@ Use it like this:
The script checks to make sure that the repo being deleted was *created* by The script checks to make sure that the repo being deleted was *created* by
the user invoking it. the user invoking it.
<a name="A7"></a>
#### (bonus) restricted admin #### (bonus) restricted admin
It's rather important to me (and presumably others in the "corporate" world) It's rather important to me (and presumably others in the "corporate" world)

20
doc/big-config.mkd
View file

@ -2,11 +2,13 @@
In this document: In this document:
* when/why do we need it? * <a href="#A1">when/why do we need it?</a>
* how do we use it? * <a href="#A2">how do we use it?</a>
* summary of settings in RC file * <a href="#A3">summary of settings in RC file</a>
* what are the downsides? * <a href="#A4">what are the downsides?</a>
* (extra coolness) usergroups and LDAP/similar tools * <a href="#A5">(extra coolness) usergroups and LDAP/similar tools</a>
<a name="A1"></a>
### when/why do we need it? ### when/why do we need it?
@ -93,6 +95,8 @@ Phew!
You can imagine what that does when you have 10,000 users and 10,000 repos. You can imagine what that does when you have 10,000 users and 10,000 repos.
Let's just say it's not pretty :) Let's just say it's not pretty :)
<a name="A2"></a>
### how do we use it? ### how do we use it?
Now, if you had all those 10,000 users and repos explicitly listed (no Now, if you had all those 10,000 users and repos explicitly listed (no
@ -138,6 +142,8 @@ configuration, the compiled file looks like this:
That's a lot smaller, and allows orders of magintude more repos and groups to That's a lot smaller, and allows orders of magintude more repos and groups to
be supported. be supported.
<a name="A3"></a>
### summary of settings in RC file ### summary of settings in RC file
The default RC file contains the following lines: The default RC file contains the following lines:
@ -156,6 +162,8 @@ you push the gitolite-admin repo with changes.
[gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb [gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb
<a name="A4"></a>
### what are the downsides? ### what are the downsides?
There is one minor issue. There is one minor issue.
@ -168,6 +176,8 @@ subset of the allowed @fragname, which would work normally, do not work now).
(If you didn't understand all that, you're probably not using delegation, so (If you didn't understand all that, you're probably not using delegation, so
feel free to ignore it!) feel free to ignore it!)
<a name="A5"></a>
### (extra coolness) usergroups and LDAP/similar tools ### (extra coolness) usergroups and LDAP/similar tools
[Please NOTE: this is all about *user* groups, not *repo* groups] [Please NOTE: this is all about *user* groups, not *repo* groups]

8
doc/progit-article.mkd
View file

@ -2,7 +2,7 @@
Git has started to become very popular in corporate environments, which tend to have some additional requirements in terms of access control. Gitolite was created to help with those requirements. Git has started to become very popular in corporate environments, which tend to have some additional requirements in terms of access control. Gitolite was created to help with those requirements.
Gitolite allows you to specify permissions not just by repository (like Gitosis does), but also by branch or tag names within each repository. That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others. Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository. That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
### Installing ### ### Installing ###
@ -25,7 +25,7 @@ Next, you clone Gitolite from the project's main site and run the "easy install"
$ cd gitolite/src $ cd gitolite/src
$ ./gl-easy-install -q gitolite gitserver sitaram $ ./gl-easy-install -q gitolite gitserver sitaram
And you're done! Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in the home directory of your workstation. You administer your gitolite setup by making changes to this repository and pushing (just like Gitosis). And you're done! Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in the home directory of your workstation. You administer your gitolite setup by making changes to this repository and pushing.
[By the way, *upgrading* gitolite is also done the same way. Also, if you're interested, run the script without any arguments to get a usage message.] [By the way, *upgrading* gitolite is also done the same way. Also, if you're interested, run the script without any arguments to get a usage message.]
@ -57,7 +57,7 @@ So once the install is done, you switch to the `gitolite-admin` repository (plac
Notice that "sitaram" (the last argument in the `gl-easy-install` command you gave earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name. Notice that "sitaram" (the last argument in the `gl-easy-install` command you gave earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name.
The config file syntax for Gitolite is *quite* different from Gitosis. Again, this is liberally documented in `conf/example.conf`, so we'll only mention some highlights here. The config file syntax for gitolite is liberally documented in `conf/example.conf`, so we'll only mention some highlights here.
You can group users or repos for convenience. The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro". You can group users or repos for convenience. The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro".
@ -90,7 +90,7 @@ That rule will just get added to the ruleset for the `gitolite` repository.
At this point you might be wondering how the access control rules are actually applied, so let's go over that briefly. At this point you might be wondering how the access control rules are actually applied, so let's go over that briefly.
There are two levels of access control in gitolite. The first is at the repository level; if you have read (or write) access to *any* ref in the repository, then you have read (or write) access to the repository. This is the only access control that Gitosis had. There are two levels of access control in gitolite. The first is at the repository level; if you have read (or write) access to *any* ref in the repository, then you have read (or write) access to the repository.
The second level, applicable only to "write" access, is by branch or tag within a repository. The username, the access being attempted (`W` or `+`), and the refname being updated are known. The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched). If a match is found, the push succeeds. A fallthrough results in access being denied. The second level, applicable only to "write" access, is by branch or tag within a repository. The username, the access being attempted (`W` or `+`), and the refname being updated are known. The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched). If a match is found, the push succeeds. A fallthrough results in access being denied.