gitolite/doc/shell-games.mkd

## avoiding the shell on the server

Gitolite now tries to prevent gitolite-admin push privileges from being used
to obtain a shell on the server.  This was not always the case (older gitolite
did not make this distinction), but I've been moving towards this for a while
now, and, while there could still be holes in that separation, they will be
fixed as and when found.

Thus, settings that have security implications can be set only from the rc
file, which needs to be edited directly on the server.  And adding a new hook
requires shell access anyway.

While this is great for my main target (corporate environments), some people
don't like it.  They want to do all of this from the *gitolite-admin* repo,
because the security concern mentioned above does not bother them.  They don't
want to log on to the server to make a change in the rc file or don't want to
run gl-setup to propagate a new set of hooks.  In addition, they may want all
of these animals versioned in the "gitolite-admin" repo itself, which
certainly makes sense.

So here's how you might do that.

First, arrange to have all your special files added to the gitolite-admin
repo.  The best option is to keep all of this in a single subdirectory (let's
call it "local" in our example).  So your `~/.gitolite.rc` might go into
`local/gitolite.rc`, and all your local hooks into `local/hooks` etc.  Add
them, commit, and push.

Note: do not create any top level directory called "conf", "contrib", "doc",
"hooks", or "src" -- those names are used by gitolite itself.

Second, create a `post-update.secondary` hook and place it in the *gitolite*
clone's `hooks/common` directory, containing the following code:

    #!/bin/bash

    [ "$GL_REPO" = "gitolite-admin" ] || exit 0

    [ -z "$GL_RC" ] && { echo "ENV GL_RC not set"; exit 1; }

    GL_ADMINDIR=`$GL_BINDIR/gl-query-rc GL_ADMINDIR`

    cp    $GL_ADMINDIR/local/gitolite.rc    $HOME/.gitolite.rc
    cp -a $GL_ADMINDIR/local/hooks/*        $GL_ADMINDIR/hooks/common

    /Full/Path/To/gl-install -q
        # the path should be the same as that for gl-auth-command in the
        # "command=" parameter of ~/.ssh/authorized_keys on the server

Don't forget to make it executable!

After this, run the upgrade instructions for the install method you used (just
as if the `post-update.secondary` file you just created came from a gitolite
software update).

All future changes to the rc file can be done via local/gitolite.rc in the
admin repo, and hooks can be added to local/hooks.

**Note**: One quirk of how gitolite [propagates hooks][hpd] is that now this
`post-update.secondary` exists in all normal repos also.  Just ignore it; it's
not doing any harm.

[hpd]: http://sitaramc.github.com/gitolite/doc/hook-propagation.html

**Warning**: Nothing in gitolite *removes* hooks, so if you delete (or even
rename) a script, it still stays on the server -- you'll have to delete them
manually from the server.

----

So what's this actually doing?

Well, first, note that `$GL_ADMINDIR` contains files from both gitolite
itself, as well as from the gitolite-admin repo.  "conf/VERSION", "src",
"doc", and "hooks" come from gitolite itself, while the other 2 files in
"conf", and all of "keydir" come from the gitolite-admin repo.  ("logs"
doesn't come from anywhere).

In addition, any other files in the "master" branch of the gitolite-admin repo
get checked out here, which in this case would mean the entire "local/"
hierarchy you created above.

Now, since the "hooks/common" directory is coming from gitolite itself,
clearly this is where the internal "install" routine expects to find new or
updated hooks to propagate.  So you just copy your local hooks (in the
"local/hooks" directory) to "hooks/common" and run the installer again.  Done!