doc/5-delegation added, doc/4 (PTA) enhanced
This is complete user documentation for delegation
This commit is contained in:
Sitaram Chamarty
parent
2f2af033f5
commit
fa5567f22c
|
|
@ -9,6 +9,7 @@ In this document:
|
|||
* simpler syntax
|
||||
* two levels of access rights checking
|
||||
* error checking the config file
|
||||
* delegating parts of the config file
|
||||
* easier to specify gitweb/daemon access
|
||||
* built-in logging
|
||||
* one user, many keys
|
||||
|
|
@ -179,6 +180,13 @@ In gitolite, you have to "compile" the config file first (this step takes the
|
|||
place of the commit+push in gitosis), and keyword typos *are* caught so you
|
||||
know right away.
|
||||
|
||||
#### delegating parts of the config file
|
||||
|
||||
You can now split up the config file and delegate the authority to specify
|
||||
access control for their own pieces. See
|
||||
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
|
||||
for details.
|
||||
|
||||
#### easier to specify gitweb/daemon access
|
||||
|
||||
Specifying gitweb and/or daemon access for a repo is simple: give "read"
|
||||
|
|
|
|||
|
|
@ -41,51 +41,60 @@ make the same changes below.
|
|||
|
||||
----
|
||||
|
||||
First, on the server, log on to the `git` userid, add a new repo called
|
||||
`gitolite-admin` to the config file, give yourself `RW` or `RW+` rights to it,
|
||||
and "compile":
|
||||
#### server side setup
|
||||
|
||||
1. First, on the server, log on to the `git` userid, add a new repo called
|
||||
`gitolite-admin` to the config file, give yourself `RW` or `RW+` rights to it,
|
||||
and "compile":
|
||||
|
||||
cd ~/.gitolite
|
||||
vim conf/gitolite.conf # add gitolite-admin repo, etc
|
||||
src/gl-compile-conf
|
||||
|
||||
Now, if you look at the "compile" script, it has an *automatic* local commit
|
||||
inside, just for safety, which kicks in every time you compile. This only
|
||||
works if it finds a ".git" directory, and it was designed as an "automatic
|
||||
backup/safety net" type of thing, in case I accidentally deleted the whole
|
||||
config file or something.
|
||||
2. Now, if you look at the "compile" script, it has an *automatic* local commit
|
||||
inside, just for safety, which kicks in every time you compile. This only
|
||||
works if it finds a ".git" directory, and it was designed as an "automatic
|
||||
backup/safety net" type of thing, in case I accidentally deleted the whole
|
||||
config file or something.
|
||||
|
||||
We need to disable this, because now we have a *better* repo, one that is
|
||||
manually pushed, and presumably has proper commit messages!
|
||||
We need to disable this, because now we have a *better* repo, one that is
|
||||
manually pushed, and presumably has proper commit messages!
|
||||
|
||||
mv .git .disable.git # yeah it's a hack, sue me
|
||||
|
||||
Now the compile command created an empty, bare, "gitolite-admin" repo, so we
|
||||
seed it with the current contents of the config and keys. (A note on the
|
||||
`GIT_WORK_TREE` variable: I avoid setting these variables in the normal way
|
||||
because I always forget to unset them later, and then when I `cd` to other
|
||||
repos they play havoc with my git commands, so this is how I do it)
|
||||
3. Now the compile command created an empty, bare, "gitolite-admin" repo, so we
|
||||
seed it with the current contents of the config and keys. (A note on the
|
||||
`GIT_WORK_TREE` variable: I avoid setting these variables in the normal way
|
||||
because I always forget to unset them later, and then when I `cd` to other
|
||||
repos they play havoc with my git commands, so this is how I do it)
|
||||
|
||||
cd ~/repositories/gitolite-admin.git
|
||||
GIT_WORK_TREE=/home/git/.gitolite git add conf/gitolite.conf keydir
|
||||
GIT_WORK_TREE=/home/git/.gitolite git commit -am start
|
||||
|
||||
Now we have to setup the post-update hook for push-to-admin to work. The hook
|
||||
should (1) make a forced checkout in the "live" config directory (which is
|
||||
`~/.gitolite`), and (2) run the compile script.
|
||||
4. Now we have to setup the post-update hook for push-to-admin to work. The hook
|
||||
should (1) make a forced checkout in the "live" config directory (which is
|
||||
`~/.gitolite`), and (2) run the compile script.
|
||||
|
||||
`src/pta-hook.sh` has the code you need; just copy it to the right place with
|
||||
the right name and make sure it is executable:
|
||||
`src/pta-hook.sh` has the code you need; just copy it to the right place with
|
||||
the right name, change the first line if needed, and make it executable:
|
||||
|
||||
# (assuming pwd is still ~/repositories/gitolite-admin.git)
|
||||
cp ~/.gitolite/src/pta-hook.sh hooks/post-update
|
||||
|
||||
# if you changed $GL_ADMINDIR in ~/.gitolite.conf, then edit the hooks
|
||||
# and change the first line:
|
||||
vim hooks/post-update
|
||||
|
||||
chmod +x hooks/post-update
|
||||
|
||||
----
|
||||
|
||||
Now get to your workstation, and
|
||||
#### client side setup
|
||||
|
||||
1. Now get to your workstation, and
|
||||
|
||||
git clone git@server:gitolite-admin.git
|
||||
|
||||
That's it, we're done. You're in gitosis land as far as this is concerned
|
||||
now. So knock yourself out. Or lock yourself out... :-)
|
||||
That's it, we're done. You're in gitosis land as far as this is concerned
|
||||
now. So knock yourself out. Or lock yourself out... :-)
|
||||
|
|
|
|||
135
doc/5-delegation.mkd
Normal file
135
doc/5-delegation.mkd
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# delegating access control responsibilities
|
||||
|
||||
[Thanks to jeromeag for forcing me to think through this...]
|
||||
|
||||
### lots of repos, lots of users
|
||||
|
||||
Gitolite tries to make it easy to manage access to lots of users and repos,
|
||||
exploiting commonalities wherever possible. (The example under "simpler, more
|
||||
powerful syntax" [here][ml] should give you an idea). As you can see, it lets
|
||||
you specify bits and pieces of the access control separately -- i.e., *all*
|
||||
the access specs for a certain repo need not be together; they can be
|
||||
scattered, which makes it easier to manage the sort of slice and dice needed
|
||||
in that example.
|
||||
|
||||
[ml]: http://github.com/sitaramc/gitolite/blob/ml/update.mkd
|
||||
|
||||
But eventually the config file will become too big. If you let only one
|
||||
person have control, he could become a bottleneck. If you give it to multiple
|
||||
people, they might make mistakes or stomp on each others' work accidentally.
|
||||
|
||||
The best way is to divide up the config file and give parts of it to different
|
||||
people. Ideally, we would delegate authority for *groups* of repos, not
|
||||
individual repos, otherwise it doesn't scale.
|
||||
|
||||
It would also be nice if we could specify what repos can be delegated to a
|
||||
particular admin, and prevent him/her from specifying access control for any
|
||||
other repos. This would be a nice "security" feature.
|
||||
|
||||
### splitting up the config file into fragments
|
||||
|
||||
To start with, recall that gitolite allows you to specify **groups** (of users
|
||||
or repos, same syntax). So the basic idea is that the main config file
|
||||
(`~/.gitolite/conf/gitolite.conf` by default) will specify some repo groups:
|
||||
|
||||
# group your projects/repos however you want
|
||||
@webbrowser_repos = firefox lynx
|
||||
@webserver_repos = apache nginx
|
||||
@malware_repos = conficker storm
|
||||
|
||||
# any other config as usual, including access control lines for any of the
|
||||
# above projects or groups
|
||||
|
||||
Now just create these files (assuming default `$GL_ADMINDIR` location):
|
||||
|
||||
~/.gitolite/conf/fragments/webbrowser_repos.conf
|
||||
~/.gitolite/conf/fragments/webserver_repos.conf
|
||||
~/.gitolite/conf/fragments/malware_repos.conf
|
||||
|
||||
Within each of those files put in whatever access control rules you want for
|
||||
the repos that are members of that group. Notice that the basenames of the
|
||||
files must be exactly the same as the name of the corresponding repo group in
|
||||
the main config file.
|
||||
|
||||
For instance, `~/.gitolite/conf/fragments/webbrowser_repos.conf` would only
|
||||
contain access control for firefox and lynx. If it referenced any other repo
|
||||
(say "storm") those lines would be ignored (and a warning message generated).
|
||||
|
||||
When you run the compile script (`src/gl-compile-conf`), the **net effect is
|
||||
as if you appended the contents of all the "fragment" files, in alphabetical
|
||||
order, to the bottom of the main file**.
|
||||
|
||||
(Except of course, while processing a fragment, it will ignore attempts to set
|
||||
permissions for repos that are not members of the same-named "repo group").
|
||||
|
||||
And that's basically it, in the simplest usage.
|
||||
|
||||
["But WAIT, there's MORE!"][bwtm]
|
||||
|
||||
[bwtm]: http://en.wikipedia.org/wiki/Ed_Valenti#But_Wait.21_There.27s_More
|
||||
|
||||
### delegating ownership of fragments
|
||||
|
||||
Splitting up the file does help, but there's also that little security issue
|
||||
-- anyone can make any change to any "fragment", unless you (once again) go
|
||||
back to Unix permissions to keep them separate.
|
||||
|
||||
Fixing that requires using "push-to-admin".
|
||||
|
||||
The page on [push-to-admin][ptd] explains clearly how to set it up. Unlike
|
||||
gitosis, I refuse to make it the default because it's a support nightmare.
|
||||
Don't get me wrong -- it's a great feature, and I use it myself, but the
|
||||
learning curve is too steep to make it *required*.
|
||||
|
||||
[ptd]: http://github.com/sitaramc/gitolite/blob/pu/doc/4-push-to-admin.mkd
|
||||
|
||||
So, having setup push-to-admin, you add these lines to the main config file,
|
||||
assuming Alice is in charge of all web browser development projects, Bob takes
|
||||
care of web servers, and Mallory, as [tradition][abe] dictates, is in charge
|
||||
of malware ;-)
|
||||
|
||||
[abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters
|
||||
|
||||
# you probably added these two lines while setting up push-to-admin
|
||||
repo gitolite-admin
|
||||
RW+ = sitaram
|
||||
# now add these 3 lines
|
||||
RW webbrowser_repos = alice
|
||||
RW webserver_repos = bob
|
||||
RW malware_repos = mallory
|
||||
|
||||
As you can see, for each repo group you want to delegate authority over,
|
||||
there's a **branch** in the `gitolite-admin` repo with the same name. Whoever
|
||||
has write access to that branch, is allowed to define rules for repos in the
|
||||
corresponding "repo group".
|
||||
|
||||
In other words, **we use gitolite's per-branch permissions to "enforce" the
|
||||
separation between the delegated configs!**
|
||||
|
||||
Here's how to use this in practice:
|
||||
|
||||
* Alice clones the `gitolite-admin` repo, creates (if not already created) and
|
||||
checks out a new branch called `webbrowser_repos`, and adds a file called
|
||||
`conf/fragments/webbrowser_repos.conf` in that branch
|
||||
|
||||
* (the rest of the contents of that branch do not matter; she can keep
|
||||
all the other files or delete all of them -- it doesn't make any
|
||||
difference. Only that one specific file is used).
|
||||
|
||||
* she writes in this file any access control rules for the "firefox" and
|
||||
"lynx" repos. She should not write access rules for any other project --
|
||||
they will be ignored
|
||||
|
||||
* Alice then commits and pushes this branch to the `gitolite-admin` repo
|
||||
|
||||
Naturally, a successful push invokes the post-update hook that you installed
|
||||
(while setting up [push-to-admin][ptd]). Here's what it does:
|
||||
|
||||
* for each branch, say `br`, of the `gitolite-admin` repo, it checks if
|
||||
there is a file called `conf/fragments/br.conf`
|
||||
|
||||
* if there is, it extracts it and copies it with the exact same name and
|
||||
path, into the `$GL_ADMINDIR` directory (`~/.gitolite` by default)
|
||||
|
||||
After that, it runs the compile script, and things work the same as described
|
||||
in the previous section.
|
||||
Loading…
Reference in a new issue