added notes on how to do more things via admin push

This commit is contained in:
Sitaram Chamarty 2010-04-12 19:56:34 +05:30
parent 4b65cc51d3
commit 55e754a09f
2 changed files with 90 additions and 12 deletions

View file

@ -10,7 +10,7 @@ In this document:
* moving pre-existing repos into gitolite * moving pre-existing repos into gitolite
* specifying gitweb and daemon access * specifying gitweb and daemon access
* custom hooks * custom hooks
* when you need your own "update" hook * hook chaining
* custom git config * custom git config
### administer ### administer
@ -99,30 +99,37 @@ for the special usernames or remove the description line.
#### custom hooks #### custom hooks
If you want to put in your own, custom, hooks every time a new repo is created You can supply your own, custom, hook scripts if you wish. Just put a
by gitolite, put a **tested** hook script in `hooks/common` of your gitolite **tested** hook script in `hooks/common` of your gitolite clone (as
clone before running easy-install. As distributed, there are only two files distributed, there are only two files there). For each file in that
there, but everything (*everything*) in that directory will get copied to the directory, a symlink pointing to it will be placed in the `hooks/`
`hooks/` subdirectory of every *new* repo created. subdirectory of every *new* repo created.
In order to push a new or updated hook script to *existing* repos as well, If you added any new hooks and wish to propagate them to *existing* repos as
just run easy install once again; it'll do it to existing repos also. well, just run gl-easy-install (or gl-setup, if you installed directly on the
server) once.
**VERY IMPORTANT SECURITY NOTE: the `update` hook in `hooks/common` is what **VERY IMPORTANT SECURITY NOTE: the `update` hook in `hooks/common` is what
implements all the branch-level permissions in gitolite. If you fiddle with 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.**
#### when you need your own "update" hook #### 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
really need the update hook functionality for their own purposes too. In 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 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. it's own "update" hook is done and everything is ready to go.
You can create this `update.secondary` hook selectively on some repos on the 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 install server, or use the mechanism in the previous section to make gitolite put it
it on *all* your repos. 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 :-)
#### custom git config #### custom git config

71
doc/shell-games.mkd Normal file
View file

@ -0,0 +1,71 @@
# 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 adding it to the *gitolite* clone and running easy install again, or
gl-setup, if you used the server-side install method, both of which require
shell access.
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 easy install 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_ADMINDIR=` cd;perl -e 'do ".gitolite.rc"; print $GL_ADMINDIR'`
cp $GL_ADMINDIR/local/gitolite.rc $HOME/.gitolite.rc
cp -a $GL_ADMINDIR/local/hooks/* $GL_ADMINDIR/hooks/common
$HOME/gitolite-install/src/gl-install -q
Now run easy-install (or gl-setup) once, and you're done.
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.
**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!