diff --git a/INSTALL b/INSTALL index 2a0184a..ce0d1d0 100644 --- a/INSTALL +++ b/INSTALL @@ -1,25 +1,99 @@ -There are 5 files you need to touch/copy +### quickinstall - example.conf - example.gitosis-lite.rc - gl-auth-command - gl-compile-conf - update-hook.pl +I assume all the files pertaining to this software are untarred and available +in the current directory. -1. copy `example.gitosis-lite.rc` as `~/.gitosis-lite.rc`. This location is - fixed for now (maybe later I'll change it to a "git config" variable). +A quick install, taking all the defaults, can be done with the following +commands; just copy and paste them into your shell: -2. edit `~/.gitosis-lite.rc` and change all the paths however you want. Be - sure to keep the perl syntax -- you *don't* have to know perl to do so, - it's fairly easy to guess in this limited case. + # this one is fixed to the location shown + cp example.gitosis-lite.rc ~/.gitosis-lite.rc -3. copy `example.conf` to whatever path you specified for `GL_CONF` in the rc - file in step 2. By default it is `~/.gitosis-lite/gitosis-lite.conf`. + # the destinations below are defaults; if you change the paths in the "rc" + # file above, these destinations also must change accordingly + # mkdir $REPO_BASE, $GL_ADMINDIR, and $GL_KEYDIR + mkdir ~/repositories + mkdir ~/.gitosis-lite + mkdir ~/.gitosis-lite/keydir + + # copy sample conf to $GL_CONF + cp example.conf ~/.gitosis-lite/gitosis-lite.conf + + # copy the 3 programs to $GL_ADMINDIR + cp update-hook.pl ~/.gitosis-lite + cp gl-auth-command ~/.gitosis-lite + cp gl-compile-conf ~/.gitosis-lite + + # optional; copy the documents also (if you untarred the package into a + # temporary directory and need to get rid of it) + cp INSTALL README.markdown ~/.gitosis-lite + +### install notes + + * At present the location of `~/.gitosis-lite.rc` is fixed (maybe later I'll + change it to a "git config" variable). + + If you edit it and change any paths, be sure to keep the perl syntax -- + you *don't* have to know perl to do so, it's fairly easy to guess in this + limited case. And of course, make sure you adjust the commands shown + above to suit the new locations + + * the config file is (by default) at `~/.gitosis-lite/gitosis-lite.conf`. Edit the file as you wish. The comments in the file ought to be clear enough but let me know if not -4. create directories for whatever you named in `GL_KEYDIR` and `REPO_BASE` - (default `~/.gitosis-lite/keydir` and `~/repositories`) + * if you want to bring in existing (bare, server) repos into gitosis-lite, + this should work: + * backup the repo, then move it to `$BASE_REPO` + * copy `$GL_ADMINDIR/update-hook.pl` to `[reponame].git/hooks/update` -- + if you don't do this, per branch restrictions will not work + * then update the keys and the config file and "compile" -5. copy `update-hook.pl` to `$GL_ADMINDIR` (default `~/.gitosis-lite`) +### administer + + * ask each user who will get access to send you a public key. See other + sources (for example + [here](http://sitaramc.github.com/0-installing/2-access-gitosis.html#generating_a_public_key)) + for how to do this + * for each "user" in `$GL_CONF`, copy their public key to a file called + "user.pub" in `$GL_KEYDIR` + * edit the config file (`$GL_CONF`) to add the new users in whatever way you + like + * backup your `~/.ssh/authorized_keys` file if you feel nervous :-) + * cd to `$GL_ADMINDIR` and run `./gl-compile-conf` + +#### optional -- if you want to be doubly sure + +It should all work, but the first couple of times you may want to check these + + * check the outputs + + * `~/.ssh/authorized_keys` should contain one line for each "user" pub + key added, between two "marker" lines (which you should please please + not remove!). The line should contain a "command=" pointing to a + `$GL_ADMINDIR/gl-auth-command` file, then some sshd restrictions, the + key, etc. + * `$GL_CONF_COMPILED` (default + `~/.gitosis-lite/gitosis-lite.conf-compiled.pm`) should contain an + expanded list of the access control rules. It may look a little long, + but it's fairly intuitive! + + * if the run threw up any "initialising empty repo" messages, check the + individual repos (inside `$REPO_BASE`) if you wish. Especially make sure + the `$REPO_BASE/[reponame].git/hooks/update` got copied OK and is + executable + +### run + +Just use it as normal. Every new repo mentioned has been created already, so +(as long as your clients are using git > 1.6.2), you can just clone it. + +And once in a while, if you're feeling particularly BOFH-ish, take a look at +`$GL_ADMINDIR/log` :-) + +### errors, warnings, etc + + * when you clone an empty repo, git seems to complain about the remote + hanging up or something. I have no idea what that is, but it doesn't seem + to hurt anything. This happens even in normal git, not just gitosis-lite. diff --git a/README.markdown b/README.markdown index 53413f6..363378e 100644 --- a/README.markdown +++ b/README.markdown @@ -1,65 +1,93 @@ # gitosis-lite +gitosis-lite is the bare essentials of gitosis, with a completely different +config file that allows (at last!) access control down to the branch level, +including specifying who can and cannot *rewind* a given branch. + In this document: - * "lite"? - * what's extra - * workflow + * why + * what's gone + * what's new + * the workflow ---- -### "lite"? +### why -I have been gitosis for a while, and have learnt a lot from it. But in a -typical $DAYJOB setting, there are some issues. It's not always Linux, so you -can't just "urpmi gitosis" and be done. "python-setuptools" isn't often -installed (and on a Solaris 9 I was trying to help remotely, we never did -manage it). And the most requested feature (see next section) had to be -written anyway. +I have been using gitosis for a while, and have learnt a lot from it. But in +a typical $DAYJOB setting, there are some issues: -While I was pondering having to finally learn python (I hate whitespace based -flow logic except for plain text; this is a *personal* opinion so pythonistas -can back off :-), I also realised that: + * it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get) + and be done + * often, "python-setuptools" isn't installed (and on a Solaris9 I was trying + to help remotely, we never did manage to install it eventually) + * the most requested feature (see "what's extra?") had to be written anyway - * no one in $DAYJOB settings will use or approve access methods that work - without any authentication, so I didn't need gitweb/daemon support in the - tool - * the idea that you admin it by pushing to a special repo is cute and - convenient, but not really necessary because of how rarely these changes - are made. +### what's gone -All of this pointed to a rewrite. In perl, naturally. +While I was pondering the need to finally learn python[1] , I also realised +that: -I also gained (and used) an unfair advantage: gits newer than 1.6.2 can clone -an empty repo, so I don't need complex logic in the permissions checking part -to *create* the repo initially -- I just create an empty bare repo when I -"compile" the config file (see "workflow" below). + * no one in $DAYJOB type environments will use or approve access methods + that work without any authentication, so I didn't need gitweb/daemon + support in the tool or in the config file + * the idea that you admin it by pushing to a special repo is nice, but not + really necessary because of how rarely these changes are made, especially + considering how much code is involved in that piece + +All of this pointed to a rewrite. In perl, naturally :-) ### what's extra? -A lot of people in my $DAYJOB type world want per-branch permissions, so I -copied the basic idea from -git.git:Documentation/howto/update-hook-example.txt. I think this is the most -significant extra I have. This includes not just who can push to what branch, -but also whether they are allowed to rewind it or not (non-ff push). +Per-branch permissions. You will not believe how often I am asked this at +$DAYJOB. This is almost the single reason I started *thinking* about rolling +my own gitosis in the first place. -### workflow +Take a look at the example config file in the repo to see how I do this. I +copied the basic idea from `update-hook-example.txt` (it's one of the "howto"s +that come with the git source tree). This includes not just who can push to +what branch, but also whether they are allowed to rewind it or not (non-ff +push). -I took the opportunity to change the workflow significantly. +However, please note the difference in the size and complexity of the +*operational code* between the update hook in that example, and in mine :-) +The reason is in the next section. - * all admin happens *on the server*, in a special directory - * after making any changes, one "compiles" the configuration. This +### the workflow + +In order to get per-branch access, you *must* use an update hook. However, +that only gets invoked on a push; "read" access still has to be controlled +right at the beginning, before git even enters the scene (just the way gitosis +currently works). + +So: either split the access control into two config files, or have two +completely different programs *both* parse the same one and pick what they +want. Crap... I definitely don't want the hook doing any parsing, (and it +would be nice if the auth-control program didn't have to either). + +So I changed the workflow completely: + + * all admin changes happen *on the server*, in a special directory that + contains the config and the users' pubkeys. But there's no commit and + push afterward. Nothing prevents you from version-controlling that + directory if you wish to, but it's not *required* + * instead, after making changes, you "compile" the configuration. This refreshes `~/.ssh/authorized_keys`, as well as puts a parsed form of the access list in a file for the other two pieces to use. -Why pre-parse? Because access control decisions are taken at two separate -stages now: +The pre-parsed form is basically a huge perl variable. It's human readable +too (never mind what the python guys say!) - * the program that is run via `~/.ssh/authorized_keys` (called - `gl-auth-command`, equivalent to `gitosis-serve`) decides whether even git - should be allowed to run (basic R/W/no access) - * the update-hook on each repo, which decides the per-branch permissions. +Advantages: all the complexity of parsing and error checking the parse is done +away from the two places where the actual access control happens, which are: -But the user specifies only one access file, and he doesn't have to know these -distinctions. So I avoid having to parse the access file in two completely -different programs by pre-compiling it and storing it as a perl "variable". + * the program that is run via `~/.ssh/authorized_keys` (I call it + `gl-auth-command`, equivalent to `gitosis-serve`); this decides whether + git should even be allowed to run (basic R/W/no access) + * the update-hook on each repo, which decides the per-branch permissions + +---- + +[1] I hate whitespace to mean anything significant except for text; this is a +personal opinion *only*, so pythonistas please back off :-)