deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

INSTALL and README pretty much done

Browse source
This commit is contained in:
Sitaram Chamarty 2009-08-24 13:29:33 +05:30 committed by Sitaram Chamarty
parent 3cddc4ca35
commit d33c408dc3
2 changed files with 160 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

106
INSTALL
View file

@ -1,25 +1,99 @@
There are 5 files you need to touch/copy ### quickinstall
example.conf I assume all the files pertaining to this software are untarred and available
example.gitosis-lite.rc in the current directory.
gl-auth-command
gl-compile-conf
update-hook.pl
1. copy `example.gitosis-lite.rc` as `~/.gitosis-lite.rc`. This location is A quick install, taking all the defaults, can be done with the following
fixed for now (maybe later I'll change it to a "git config" variable). commands; just copy and paste them into your shell:
2. edit `~/.gitosis-lite.rc` and change all the paths however you want. Be # this one is fixed to the location shown
sure to keep the perl syntax -- you *don't* have to know perl to do so, cp example.gitosis-lite.rc ~/.gitosis-lite.rc
it's fairly easy to guess in this limited case.
3. copy `example.conf` to whatever path you specified for `GL_CONF` in the rc # the destinations below are defaults; if you change the paths in the "rc"
file in step 2. By default it is `~/.gitosis-lite/gitosis-lite.conf`. # 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 Edit the file as you wish. The comments in the file ought to be clear
enough but let me know if not enough but let me know if not
4. create directories for whatever you named in `GL_KEYDIR` and `REPO_BASE` * if you want to bring in existing (bare, server) repos into gitosis-lite,
(default `~/.gitosis-lite/keydir` and `~/repositories`) 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.

112
README.markdown
View file

@ -1,65 +1,93 @@
# gitosis-lite # 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: In this document:
* "lite"? * why
* what's extra * what's gone
* workflow * what's new
* the workflow
---- ----
### "lite"? ### why
I have been gitosis for a while, and have learnt a lot from it. But in a I have been using gitosis for a while, and have learnt a lot from it. But in
typical $DAYJOB setting, there are some issues. It's not always Linux, so you a typical $DAYJOB setting, there are some issues:
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.
While I was pondering having to finally learn python (I hate whitespace based * it's not always Linux; you can't just "urpmi gitosis" (or yum or apt-get)
flow logic except for plain text; this is a *personal* opinion so pythonistas and be done
can back off :-), I also realised that: * 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 ### what's gone
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.
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 * no one in $DAYJOB type environments will use or approve access methods
an empty repo, so I don't need complex logic in the permissions checking part that work without any authentication, so I didn't need gitweb/daemon
to *create* the repo initially -- I just create an empty bare repo when I support in the tool or in the config file
"compile" the config file (see "workflow" below). * 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? ### what's extra?
A lot of people in my $DAYJOB type world want per-branch permissions, so I Per-branch permissions. You will not believe how often I am asked this at
copied the basic idea from $DAYJOB. This is almost the single reason I started *thinking* about rolling
git.git:Documentation/howto/update-hook-example.txt. I think this is the most my own gitosis in the first place.
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).
### 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 ### the workflow
* after making any changes, one "compiles" the configuration. This
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 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. access list in a file for the other two pieces to use.
Why pre-parse? Because access control decisions are taken at two separate The pre-parsed form is basically a huge perl variable. It's human readable
stages now: too (never mind what the python guys say!)
* the program that is run via `~/.ssh/authorized_keys` (called Advantages: all the complexity of parsing and error checking the parse is done
`gl-auth-command`, equivalent to `gitosis-serve`) decides whether even git away from the two places where the actual access control happens, which are:
should be allowed to run (basic R/W/no access)
* the update-hook on each repo, which decides the per-branch permissions.
But the user specifies only one access file, and he doesn't have to know these * the program that is run via `~/.ssh/authorized_keys` (I call it
distinctions. So I avoid having to parse the access file in two completely `gl-auth-command`, equivalent to `gitosis-serve`); this decides whether
different programs by pre-compiling it and storing it as a perl "variable". 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 :-)