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="#_gl_pre_git_hook">"gl-pre-git" 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 (except when the documentation says you should, for example to add
custom hooks).  In particular, adding new repositories or users or changing
the access control rules should not be done directly on the server.  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
    [doc/gitolite.conf.mkd][confmkd] 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.

<font color="red">**IMPORTANT WARNINGS**</font>

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

  * Do not under any conditions put anything in `hooks/gitolite-admin` --
    nothing in gitolite requires you to do anything here.  Leave it alone!

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

#### "gl-pre-git" hook

Although git has lots of nice hooks you can tap into, they all run only on a
push.  There's nothing that runs on a fetch or a clone, and there's no way to
run something *before* git-receive-pack or git-upload-pack, (as the case may
be) are invoked.

That's what the `gl-pre-git` hook is for.  If an executable hook called
`gl-pre-git` is present, it will be invoked with the current directory set to
`repo.git`, and with a single argument which will be either `R` or `W`
depending on what the client is trying to do.  The environment variables
`GL_USER` and `GL_REPO` are available.  STDOUT will be forced to STDERR before
it is called, to avoid confusing the client.

If the code returns anything other than 0, gitolite will terminate the
operation (i.e., not run git at all), just like many git hooks do, so make
sure you end with `exit 0` or equivalent.

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

#### hook chaining

Sometimes you need to use git hooks for your own purposes (site-local
validations, CI integration, email notifications, or the ever popular "live
website update"!).  However, the hooks you want to use may already be in use
by gitolite.

This section will tell you what to do in such cases.  First, let's list the
hooks that gitolite uses:

  * The `update` hook is used in all repos and is critical to gitolite's
    access control!

  * The `post-receive` hook is used in all repos but only if mirroring has
    been enabled.  Shipped as `post-receive.mirrorpush`, it is renamed to
    'post-receive' and installed as part of the mirroring setup.

  * The `post-update` hook is used in the `gitolite-admin` repo only, to
    "compile" the configuration and so on.

To run your own 'update' hook, just put it in a file called `update.secondary`
and install it as a hook.  Gitolite's update hook will automatically chain to
it, taking care to pass it the same 3 arguments the original update hook
received from git.

<font color="gray">

>   In addition, gitolite now contains the basic infrastructure to support
>   multiple 'update' hooks without having to remember to chain them yourself.
>   See `hooks/common/update.secondary.sample` for instructions.

</font>

For `post-receive`, (if using mirroring) do the opposite.  You're normally
expected to rename the shipped 'post-receive.mirrorpush' to 'post-receive',
but don't do this.  Instead, simply run `hooks/post-receive.mirrorpush` at the
end of *your* hook code.  Do not worry about replicating STDIN (the documented
way in which a post-receive hook receives its input) because the mirroring
code does not use it.

To run your own `post-update` hook on normal repos, just install a hook called
'post-update' the usual way.  It'll be installed on all normal repos but not
on the special gitolite-admin repo.  If you need that for the gitolite-admin
repo, you'll have to call it `post-update.secondary`.

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.

**Assumptions**

  * you have not changed `$REPO_BASE` on 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.rc` on the old server:

        exit 1;

  * (new server) **copy** the repos to the new server, **except** the
    `gitolite-admin` repo and files called `gitolite-hooked` in the `hooks`
    directory 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

      * edit `~/.ssh/config` and change the line that says `host gitolite` to
        `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.rc` file to match the settings on
    the old server, if needed.  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!  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!

<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 has two pre-defined, "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.  Something like this:

    repo    foo bar baz
        R   =   gitweb daemon

This gives you a quick way to offer multiple repos up for gitweb and/or daemon
access.

However, setting a description for the project also enables gitweb permissions
so you can do it that way if you want.  Of course in this case you have to
deal with each repo separately.  Add lines like this to gitolite.conf:

    foo = "some description"
    bar = "some other description"
    baz = "yet another description"

You can also specify an owner for gitweb to show, if you like; for example I
might use:

    gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git"

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 `doc/gitolite.conf.mkd` 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
[confmkd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html