gitolite/doc/2-admin.mkd

# administering and running gitolite

In this document:

  * <a href="#_please_read_this_first">please read this first</a>
  * <a href="#_adding_users_and_repos">adding users and repos</a>
  * <a href="#_using_hooks">using hooks</a>
      * <a href="#_custom_hooks">custom hooks</a>
      * <a href="#_gl_post_init_hook">"gl-post-init" hook</a>
      * <a href="#_hook_chaining">hook chaining</a>
      * <a href="#_environment_variables_available_to_hooks">environment variables available to hooks</a>
  * <a href="#_other_features">other features</a>
      * <a href="#_moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
      * <a href="#_moving_the_whole_thing_from_one_server_to_another">moving the whole thing from one server to another</a>
      * <a href="#_specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
      * <a href="#_custom_git_config">custom git config</a>

----

<a name="_please_read_this_first"></a>

### 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
that clone.

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.

<a name="_adding_users_and_repos"></a>

### adding users and repos

  * 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

  * 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
    periods and underscores

  * copy all these `*.pub` files to `keydir` in your gitolite-admin repo
    clone.  You can also organise them into various subdirectories of `keydir`
    if you wish, since the entire tree is searched.

  * edit the config file (`conf/gitolite.conf` in your admin repo clone).  See
    `conf/example.conf` in 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 `.pub` extension

  * 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="_using_hooks"></a>

### using hooks

<a name="_custom_hooks"></a>

#### custom hooks

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.**

<a name="_gl_post_init_hook"></a>

#### "gl-post-init" hook

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.

<a name="_hook_chaining"></a>

#### hook chaining

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 `update.secondary` when
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 `post-update.secondary`
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 (`update.secondary` and `post-update.secondary`) are
merely the defaults.  You can change them to anything you want; look in
conf/example.gitolite.rc for details.

<a name="_environment_variables_available_to_hooks"></a>

#### 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

<a name="_other_features"></a>

### other features

<a name="_moving_pre_existing_repos_into_gitolite"></a>

#### 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 `.git` suffix) to
    `conf/gitolite.conf` in your gitolite-admin repo clone.  Then add, commit,
    push.

<a name="_moving_the_whole_thing_from_one_server_to_another"></a>

#### 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.

[If you feel like doing it on your own, just be aware that copying the repos
as they are *may* give you wrong hooks.  Or worse, since the hooks are
symlinks, a dangling symlink means it won't get executed.  And an update hook
that does not get executed is **BAD** :-)]

The following should work for all cases.  Note that this is a somewhat
pessimal series of instructions -- if you know how it all hangs together you
can probably think of easier ways.

  * (workstation) reclone your current admin repo (from the old server) to a
    backup location for safety

        cd $HOME; mkdir admin-bkp; cd admin-bkp
        git clone git@oldserver:gitolite-admin
            # git clone gitolite:gitolite-admin if you used the "from-client"
            # method to install

  * (workstation) if your old server was installed using the "from-client"
    method, edit `~/.ssh/config` and change the line that says `host gitolite`
    to `host old-gitolite`.  Don't change it to "host gitolite-old" or
    anything that matches the string "host gitolite" :-)

  * (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.rc` on the old server:

        exit 1;

  * (new server) copy the entire repositories directory (or wherever you have
    `$REPO_BASE` pointing to) from the old server to the new server.

        # (on new server, assuming default $REPO_BASE on both machines)
        cd $HOME
        rsync -avP git@oldserver:repositories .

    Note the syntax of that rsync command carefully; one extra "/" somewhere
    and it will do something else :-)  Or use some other method to copy the
    whole thing.

  * (workstation, new server) make a brand new installation on the new server.
    You must use the same keypair for the admin, with the same name.  However,
    it is not necessary to use the same *install method*; if one of the other
    install methods is better for you on the new server, go for it.

    This will end up overwriting the rsync-copied gitolite-admin repo with a
    brand new "factory default" one.

  * (new server) manually adjust the `~/.gitolite.rc` file to match the
    settings on the old server.  Do not copy the entire file outright -- some
    of the variables (notably `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS`) are
    installation dependent and should not be touched!

  * (workstation) go to your backup repo and force push it up to the new
    server:

        cd ~/admin-bkp/gitolite-admin
        git push -f git@newserver:gitolite-admin
            # git push -f gitolite:gitolite-admin if you used the
            # "from-client" method to install

<a name="gwd"></a>

<a name="_specifying_gitweb_and_daemon_access"></a>

#### 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: `daemon` and `gitweb`.

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-ok` in 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_list` when setting up gitweb)
  * put the description, if given, in `$repo/description`

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 `@all`
(that is, using either `repo @all` or `R = @all`), will not work unless you
set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `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
environment**.

<a name="_custom_git_config"></a>

#### 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
variable called `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).

Please see `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 `--add`, the `value_regex`,
etc.

[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key