administering and running gitolite
In this document:
- please read this first
- adding users and repos
- using hooks
- other features
please read this first
Unless you know what you're doing, do not do anything manually on the server, like adding new repositories or users or changing the access control rules. Things will break. For example, if you manually create a repo on the server, it will not have the required "update" hook, without which there is no access control for pushes.
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 clone, and pushing those changes back.
The installation steps in the previous section include the steps to do this
clone, so you should already have one on your workstation, in
~/gitolite-admin. You can of course clone it anywhere else you want and use
Either way, make sure you
cd into this clone first.
Note: some of the paths in this document use variable names. Just refer to
~/.gitolite.rc for the correct values for your installation.
Once you've cloned it, you're ready to add users and repos.
adding users and repos
ask each user who will get access to send you a public key. See other sources (for example here) for how to do this
rename each public key according to the user's name, with a
john-smith.pub. You can also use periods and underscores
copy all these
keydirin your gitolite-admin repo clone. You can also organise them into various subdirectories of
keydirif you wish, since the entire tree is searched.
edit the config file (
conf/gitolite.confin your admin repo clone). See
conf/example.confin the gitolite source for details on what goes in that file, syntax, etc. Just add new repos as needed, and add new users and give them permissions as required. The users names should be exactly the same as their keyfile names, but without the
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.
You can supply your own, custom, hook scripts if you wish. Install gitolite as usual, then:
- if you installed using "from-client" method (gl-easy-install):
- go to the gitolite source clone from which you did the original install
- add your new hook into "hooks/common"
- run src/gl-easy-install with the same arguments as you ran the first time
- if you installed using one of the other methods
- go to ~/.gitolite/hooks/common on the server and put your new hook there
- now run "gl-setup" again
You can use this procedure to install new hooks as well as to update hooks that you had previously installed.
VERY IMPORTANT SECURITY NOTE: the
update hook in
hooks/common is what
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
accidentally, or all your fancy per-branch permissions will stop working.
Sometimes it is necessary to do something whenever a new repo is created. If you need this functionality, just supply a hook called "gl-post-init" with whatever code you want in it.
Gitolite basically takes over the update hook for all repos, but some setups
really need the update hook functionality for their own purposes too. In
order to allow this, Gitolite now exec's a hook called
it's own "update" hook is done and everything is ready to go.
You can create this
update.secondary hook manually on selected repos on the
server, or use the mechanism in the previous section to make gitolite put it
on all your repos.
Similarly, gitolite also takes over the post-update hook for the special
"gitolite-admin" repo. This hook will also chain to a
if such a hook exists. People wishing to do exotic things on the server side
when the admin repo is pushed should see doc/shell-games.notes for how to
exploit this :-)
Finally, these names (
merely the defaults. You can change them to anything you want; look in
conf/example.gitolite.rc for details.
environment variables available to hooks
The following environment variables are set, and may be useful for any custom processing you wish to do in your hook code:
GL_USER-- the user doing the push
GL_REPO-- the reponame
GL_REPO_BASE_ABS-- the absolute base path where all the repos are kept
The following variables are also set, but are generally less useful:
GL_BINDIR-- where all the binaries live
GL_ADMINDIR-- common directory for many gitolite things
moving pre-existing repos into gitolite
One simple way to add a pre-existing repo to gitolite is to let gitolite create it as a brand new repo as in the previous section, then do the following:
cd your-copy-of-the-repo # make sure all the branches are correct and no extra stuff, "temp" # branches, etc., are present git push --all git@server:reponame git push --tags git@server:reponame
(You could also use "git push --mirror" instead of separately doing branches
and tags, but that will carry across your remote refs also, and typically
you may not want that. Anyway please do a
git ls-remote git@server:repo to
make sure all the stuff you want went through, and is named correctly).
All this is actually very simple and easily done. However, if you have many existing repos to add, this can be time-consuming and error-prone. Here's how to take a bunch of existing repos and add them to gitolite:
make sure they're bare repos ;-)
log on to the server and copy the repos to
$REPO_BASE(which defaults to
~/repositories), making sure that the directory names end in ".git".
back on your workstation, add each repo (without the
conf/gitolite.confin your gitolite-admin repo clone. Then add, commit, push.
moving the whole thing from one server to another
[NOTE: I would appreciate help testing these instructions]
Just copying everything won't work unless everything on the new server is exactly the same. I suggest you don't try it unless you know what you're doing.
- you have not changed
$REPO_BASEon either of the servers; if you did, substitute accordingly
- the admin's name is "YourName" -- again, substitute accordingly!
- the "hosting user" on both servers is "git". Substitute whatever you're actually using (for example, if you're installing using RPM/DEB, this would be "gitolite")
There are many ways of doing this, but the most generic set of steps are given below. Please follow all the steps; do not skip or improvise! Ask me if things are not clear -- you can help me fine tune this document :-)
(old server) disable the old server so your users will not push any changes to it. There are several ways to do this, but the simplest is to insert this line at the top of
~/.gitolite.rcon the old server:
(new server) copy the repos to the new server, except the
gitolite-adminrepo and files called
hooksdirectory of each repo.
That sounds complicated but it's not. It's just:
cd $HOME rsync -a olduser@oldhost:repositories . mv repositories/gitolite-admin.git $HOME/old-gitolite-admin.git find repositories -name gitolite-hooked | xargs rm
(workstation) if your old server was installed using the "from-client" method, and you intend to use the same method to install the new server, then
~/.ssh/configand change the line that says
host old-gitolite, or in fact anything that does not match the string "host gitolite" :-)
(workstation, new server) install gitolite normally on your new server. Use whatever install method suits you, but you must use the same name for the admin ("YourName" in the install instructions). You may use a different keypair if you need to, or use the same one that currently gets access to the old server.
(new server) edit the
~/.gitolite.rcfile to match the settings on the old server, if needed. Do not copy the entire file outright -- some of the variables (notably
GL_PACKAGE_HOOKS) are installation dependent and should not be touched! Do a diff or a vimdiff and copy across only what you know you changed on the old server.
(workstation) push the config to the new server. To do this, go to your admin clone, and:
if you used a different keypair when installing to the new server, copy that pubkey to this clone into
keydir/Yourname.pub, then add and commit the change to the pubkey
cd gitolite-admin cp path/to/new/YourName.pub keydir/YourName.pub git add keydir git commit -m "new server, new key"
if you did not use a different keypair, just make a dummy commit
git commit -m "new server" --allow-empty
set the URL for the new server
git remote --set-url origin git@newserver:gitolite-admin # if you used easy install this will be "gitolite:gitolite-admin"
push the config, including past history
git push -f
And that should be that!
specifying gitweb and daemon access
This is a feature that I personally do not use (corporate environments don't like unauthenticated access of any kind to any repo!), but someone wanted it, so here goes.
Gitolite defines two "special" usernames:
To make a repo or repo group accessible via "git daemon", just give read
permission to the special user "daemon". Similarly, give read permission to
gitweb to allow the gitweb CGI to show the repo.
This gives you a quick way to offer multiple repos up for gitweb/daemon access.
However, setting a description for the project also enables gitweb permissions so you may as well use that method and kill two birds with one stone, like so:
gitolite = "fast, secure, access control for git in a corporate environment"
You can also specify an owner for gitweb to show, if you like:
gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"
Note that gitolite does not install or configure gitweb/git-daemon -- that is a one-time setup you must do separately. All gitolite does is:
- for daemon, create the file
git-daemon-export-okin the repository
- for gitweb, add the repo (plus owner name, if given) to the list of
projects to be served by gitweb (see the config file variable
$PROJECTS_LIST, which should have the same value you specified for
$projects_listwhen setting up gitweb)
- put the description, if given, in
The "compile" script will keep these files consistent with the config settings -- this includes removing such settings/files if you remove "read" permissions for the special usernames or remove the description line.
Please note that giving permissions to these special users via
(that is, using either
repo @all or
R = @all), will not work unless you
set the rc-file variable
1. Also, NOTE
that giving them read access to
repo @all means the
gitolite-admin repo is
also accessible. It is upto you to decide if that is OK in your
custom git config
The custom hooks feature is a blunt instrument -- all repos get the hook you specified and will run it. In order to make it a little more fine-grained, you could set your hooks to only work if a certain "gitconfig" variable was set. Which means we now need a way to specify "git config" settings on a per repository basis.
[Note: this feature is disabled by default. Read the comments around a
GL_GITCONFIG_KEYS in the rc file, then set it to some
appropriate value, to enable this feature.]
Thanks to Teemu (teemu dot matilainen at iki dot fi), gitolite now does this very easily. For security reasons, this can only be done from the master config file (i.e., if you're using delegation, the delegated admins cannot specify git config settings).
conf/example.conf for syntax. Note that this only supports the
basic forms of the "git config" command:
git config section.key value # value may be an empty string git config --unset-all section.key
It does not (currently) support other options like