9.6 KiB
F=pictures gitolite in pictures
Well, they say a picture speaks a thousand words, so here're a few!
NOTE: if you're viewing this file in raw text, please note that some characters in text within a ditaa drawing may not be ASCII. This is due to a ditaa flaw that treats even a single hyphen as a line drawing character, so I had to use Unicode 2010 for it. I expect that I will have to resort to similar tricks for colon, equals, and many others like it if and when I need those in text within a ditaa diagram.
installation and setup
Here's a picture showing the "non-root" install. We assume Alice is the gitolite admin, and "git" is the hosting user on the server.
.aa
Gitolite install and setup sequence (non_root method, default values)
------------------------------------------------------------------------
/-----------------\ /----------------------\
| user "alice" | | user "git" |
|(on workstation) | | (on server) |
|cPNK | |cGRE |
\-----------------/ \----------------------/
/-----------------\ /----------------------\
|~/.ssh/id_rsa.pub|------->| alice.pub |-----\
\----------+------/ (1) \----------------------/ |
/----------------------\ |
/-------------->| ~/gitolite |-----+
| (2) /-----| | |
| | \----------------------/ |
| | /----------------------\ |
| | | ~/bin |-----+
| \---->| ~/share | |
| (3) \----------------------/ |
/----------+------\ /----------------------\ |
| (github) | | ~/.gitolite.rc | |
|cBLU | |~/.ssh/authorized_keys|<----/
\-----------------/ | ~/.gitolite | (4)
| ~/repositories |
\----------------------/
The files names are there only for information. You do not have to do anything to them yourself; in fact you should not! You only need the command for each step shown:
- copy the admin's pubkey to the server as "alice.pub"
git clone git://github.com/sitaramc/gitoliteor equivalentgitolite/src/gl-system-installgl-setup alice.pub
Note also that you only need ONE real user on the server. In our example it is git. In particular, you do NOT create Unix userids for your gitolite users.
adding users to gitolite
Once you've done the install, here's how you add users.
.aa
Adding users to gitolite
------------------------------------------------------------------------
/-------------------\ /-----------------------\
| user "git" | | user "alice" |
| (on server) | | (on workstation) |
| cGRE | | cPNK |
\-------------------/ \-----------------------/
/-------------------\ /-----------------------\
| (gitolite) |----------->| ~/gitolite‐admin |
| | (1) | |
| | | |
| |<-----------| |
\-------------------/ (3) \-----------------------/
/-----------------------\
/-------------------\ | (alice@workstation) |
| bob cYEL |----\ |~/gitolite‐admin/keydir|
| ~/.ssh/id_rsa.pub | | |cPNK |
\-------------------/ | +-----------------------+
\------>| bobby.pub |
/-------------------\ (2) +-----------------------+
| carol cYEL |----------->| carol.pub |
| ~/.ssh/id_rsa.pub | +-----------------------+
\-------------------/ | (...) |
\-----------------------/
All this is done from the admin (Alice)'s workstation. The steps are:
git clone git@server:gitolite-admin- obtain pubkeys from each user. Email, USB, DHL, pigeon post, owl mail,
any method you like. Rename each received file to the name of the user,
add a ".pub" at the end, copy it into
keydir/in the gitolite-admin repo you cloned. git add keydir, thengit commit, thengit push
You do NOT need to add Carol or Bob as real (Unix) users. You do NOT add their keys directly anywhere on the server; you do it by cloning, adding keys, and pushing.
adding repos to gitolite
Adding a repo is even easier. It's so easy that you don't really need a picture. OK maybe a small one:
.aa
Adding repos to gitolite
------------------------------------------------------------------------
/-------------------\ /-----------------------\
| user "git" | | user "alice" |
| (on server) | | (on workstation) |
| cGRE | | cPNK |
\-------------------/ \-----------------------/
/-------------------\ /-----------------------\
| (gitolite) |----------->| ~/gitolite‐admin |
| | (1) | |
| | | |
| |<-----------| |
\-------------------/ (3) \-----------------------/
/-----------------------------------\
| (alice@workstation) |
|~/gitolite‐admin/conf/gitolite.conf|
| cPNK |
+-----------------------------------+
| <config lines for repo foo> |
+-----------------------------------+
| <config lines for repo bar> |
+-----------------------------------+
| (...) |
\-----------------------------------/
Again, all this is done from the admin (Alice)'s workstation. Steps one and three are the same as for adding users, but step 2 consists of adding config lines for whatever repo you want too add.
-
git clone git@server:gitolite-admin -
edit
conf/gitolite.confin the repo clone you just made. Add repo paragraphs, maybe like this, and save the file:repo foo RW+ = alice RW = bob -
git add conf/gitolite.conf, thengit commit, thengit push
You do NOT add the repos directly anywhere on the server; you do it by cloning, adding keys, and pushing.
#flow gitolite flow
This is the overall flow of gitolite, showing how the various parts fit together. This is particularly useful for an admin to see where his site-local hooks fit, how they get called, and what stages of the process they affect.
Legend: diamonds are decision boxes whose results can abort the operation. Arrows are calls/invocations. Dashed lines just point to sub-parts of the process on the left side. Blue processes are external to gitolite. Green is gitolite code. Yellow is site-local code that you (the admin of your site) can add, to influence gitolite's behaviour.
Authentication (AUTHN) is typically done by sshd, but could also be httpd
etc. This step invokes gl-auth-command (GLAC), which is the main entry
point for gitolite, passing it a username and a command. The most common
commands look like one of these:
git-upload-pack 'repo'
git-receive-pack 'repo'
GLAC first checks the command to see if it is a read or a write (RW) operation (upload-pack is a read, receive-pack is a write).
At this point, GLAC knows the username, the reponame, and the type of operation. It executes the first [level][2levels] access check (AC1), which passes if the user has at least one ref for which the operation is allowed.
Note that neither "deny" rules nor the rule sequences are taken into account for this step. For instance, user "alice" will pass this step even with this configuration:
repo foo
- = alice
RW = alice
although some other user, say "bob", will not.
.gv
"Gitolite Flow"
rankdir=LR
edge[dir=forward]
[b] AUTHN
[g] GLAC
[g] RW
<> [g] AC1
<> [y] PGH
[b] Git
[g] UP
<> [g] AC2
AUTHN .. GLAC
GLAC -- RW
GLAC -- AC1
GLAC .. PGH
GLAC .. Git .. UP
UP -- AC2
<> [y] SEC
UP .. SEC
Once AC1 has passed, GLAC calls the [gl-pre-git][pre-git] hook (PGH), if
it is present. This hook allows the admin to add his own checks at this first
stage and even abort the operation if needed.
If PGH passes, GLAC now invokes git itself, which runs the command specified.
If the command is git-upload-pack, nothing else happens and the process
completes.
However, if it is a push operation (git-receive-pack) then git calls the
update hook (UP), per man githooks. The update hook executes the second
[level][2levels] access check (AC2), and depending on its success, the
operation succeeds or fails.
The update hook calls a secondary hook, [update.secondary][hookchaining]
(SEC) if it exists. Similar to PGH, this allows the admin to add
site-local checks before allowing the update to complete.