document overhaul
- explicit 'list' gives way to mindmap, ... - 'fm2mt.pl' to produce master-toc.mkd from the mindmap - mkdoc no longer ignores master-toc.mkd, calls fm2mt.pl itself and LOTS of changes to the actual docs
This commit is contained in:
Sitaram Chamarty
parent
7c6728af89
commit
de40461d9a
72
doc/WARNINGS.mkd
Normal file
72
doc/WARNINGS.mkd
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
# WARNINGS
|
||||
|
||||
Gitolite does NOT like it if you fiddle with files, directories, permissions,
|
||||
etc., on the server except as directed in the documentation. Gitolite also
|
||||
expects all the directories and files it manages/uses to be owned by the
|
||||
hosting user and not have strange permissions and ownerships.
|
||||
|
||||
Very few people have fallen foul of this, but the ones who *did* became very
|
||||
obnoxious about it, hence this warning.
|
||||
|
||||
Gitolite depends on several system-installed packages: openssh, git, perl, sh
|
||||
being the main ones. They should all be configured sensibly and with most of
|
||||
the normal defaults. (For example, if your sshd config says the authorized
|
||||
keys file should be placed in some directory other than the default, expect
|
||||
trouble).
|
||||
|
||||
----
|
||||
|
||||
For the entertainment of the sensible majority, and as a way of thanking all
|
||||
of you, here are some examples of requests (demands in some cases) I have
|
||||
received over the last couple of years.
|
||||
|
||||
* deleting environment variables copied from client session
|
||||
|
||||
demand: add code to delete certain environment variables at startup
|
||||
because "the openssh servers in the linux distribution that [he] use[s],
|
||||
are configured to copy `GIT_*` variables to the remote session".
|
||||
|
||||
This is wrong on so many levels it's almost plonk-able!
|
||||
|
||||
* using `cp` instead of `ln`
|
||||
|
||||
Guy has an NTFS file system mounted on Linux. So... no symlinks (an NTFS
|
||||
file system on Windows works fine because msysgit/cygwin manage to
|
||||
*simulate* them. NTFS mounted on Linux won't do that!)
|
||||
|
||||
He wanted all the symlink stuff to be replaced by copies.
|
||||
|
||||
No. Way.
|
||||
|
||||
* non-bare repos on the server
|
||||
|
||||
Some guy gave me a complicated spiel about git-svn not liking bare repos
|
||||
or whatever. I tuned off at the first mention of those 3 letters so I
|
||||
don't really know what the actual problem was.
|
||||
|
||||
But it doesn't matter. Even if someone (Ralf H) had not chipped in with a
|
||||
workable solution, I still would not do it. A server repo should be bare.
|
||||
Period.
|
||||
|
||||
* incomplete ownership of `GL_REPO_BASE`
|
||||
|
||||
This guy had a repo-base directory where not all of the files were owned
|
||||
by the git user. As a result, some of the hooks did not get created. He
|
||||
claimed my code should detect OS-permissions issues while it's doing its
|
||||
stuff.
|
||||
|
||||
No. I refuse to have the code constantly look over its shoulder making
|
||||
sure fundamental assumptions are being met.
|
||||
|
||||
* empty template directory
|
||||
|
||||
(See man git-init for what a template directory is).
|
||||
|
||||
The same guy with the environment variables had an empty template
|
||||
directory because he "does not like to have sample hooks in every
|
||||
repository". So naturally, the hooks directory does not get created when
|
||||
you run a `git init`. He expects gitolite to compensate for it.
|
||||
|
||||
Granted, it's only a 1-line change. But again, this falls under
|
||||
"constantly looking over your shoulder to double check fundamental
|
||||
assumptions". Where does it end?
|
||||
34
doc/add.mkd
34
doc/add.mkd
|
|
@ -1,34 +0,0 @@
|
|||
# adding users and repos
|
||||
|
||||
Do NOT add repos directly on the server. Clone the 'gitolite-admin' repo to
|
||||
your workstation, make changes to it, then add, commit, and push. When the
|
||||
push hits the server, the server "acts" upon your changes.
|
||||
|
||||
Full documentation on the conf file is [here][conf].
|
||||
|
||||
Here's a sample sequence, on your workstation, after your install is done
|
||||
|
||||
git clone git@host:gitolite-admin
|
||||
cd gitolite-admin
|
||||
vi conf/gitolite.conf
|
||||
|
||||
# now add lines like these:
|
||||
repo foo
|
||||
RW+ = me
|
||||
RW = alice
|
||||
R = wally
|
||||
# now save the file and add it
|
||||
git add conf
|
||||
|
||||
# add a couple of users; get their pubkeys by email or something, then:
|
||||
cp /some/where/alice.pub keydir
|
||||
cp /else/where/wally.pub keydir
|
||||
git add keydir
|
||||
|
||||
# now commit and push
|
||||
git commit -m 'added repo foo'
|
||||
git push
|
||||
|
||||
# at this point gitolite will create the new repo 'foo' (if it did not
|
||||
# already exist) then update the authorized keys file to include alice and
|
||||
# wally's pubkeys
|
||||
42
doc/admin.mkd
Normal file
42
doc/admin.mkd
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# gitolite administration
|
||||
|
||||
## #server server-side administration
|
||||
|
||||
The following activities require command line access to the server
|
||||
|
||||
* changing anything in the [rc][] file
|
||||
* installing custom [hooks][], whether to all repos or just some repos
|
||||
* moving [existing][] (bare) repos into gitolite control
|
||||
|
||||
Please read the [WARNINGS][] page first.
|
||||
|
||||
## #conf access control (the gitolite.conf file)
|
||||
|
||||
Most of gitolite's power is in the conf/gitolite.conf file, which specifies
|
||||
detailed access control for repos.
|
||||
|
||||
### #confex example of a conf file
|
||||
|
||||
Here is an example of a simple conf/gitolite.conf file.
|
||||
|
||||
@staff = dilbert alice # line 1
|
||||
@projects = foo bar # line 2
|
||||
|
||||
repo @projects baz # line 3
|
||||
RW+ = @staff # line 4
|
||||
- master = ashok # line 5
|
||||
RW = ashok # line 6
|
||||
R = wally # line 7
|
||||
|
||||
config hooks.emailprefix = '[%GL_REPO] ' # line 8
|
||||
|
||||
Use the following links to learn more:
|
||||
|
||||
* the basic [syntax][] -- comments, whitespace, include files, etc.
|
||||
* defining [groups][], as in lines 1 and 2
|
||||
* adding and removing [users][]
|
||||
* adding and removing [repos][], as in line 3
|
||||
* defining access [rules][], as in lines 4, 5, 6, and 7
|
||||
* gitolite [options][]
|
||||
* [git config][git-config] keys and values, as in line 8
|
||||
* ["wild"][wild] repos -- ad hoc, user-created, repos
|
||||
31
doc/conf.mkd
31
doc/conf.mkd
|
|
@ -1,31 +0,0 @@
|
|||
# the gitolite.conf file
|
||||
|
||||
This file is the crux of all of gitolite's access control. The basic syntax
|
||||
is very simple.
|
||||
|
||||
Note: `<user>+` means one or more user or user group names, `<repo>+` means
|
||||
one or more repo or repo group names, and `<refex>*` means zero or more
|
||||
refexes.
|
||||
|
||||
* [group][group] definitions (optional, for convenience)
|
||||
|
||||
@<group> = <user>+
|
||||
@<group> = <repo>+
|
||||
|
||||
* [repo][repo] definitions and access [rules][]
|
||||
|
||||
repo <repo>+
|
||||
<perm> <refex>* = <user>+
|
||||
# one or more such lines
|
||||
|
||||
* [gitolite options][options] that apply to the repo(s) in the last
|
||||
"repo ..." line, for example:
|
||||
|
||||
option deny-rules = 1
|
||||
|
||||
* [git config][git-config] keys and values that also apply to the last named
|
||||
repo(s), for example:
|
||||
|
||||
config hooks.emailprefix = '[%GL_REPO] '
|
||||
|
||||
In addition, you can also have [include][] statements.
|
||||
17
doc/cust.mkd
17
doc/cust.mkd
|
|
@ -2,17 +2,20 @@
|
|||
|
||||
Much of gitolite (g3)'s functionality comes from programs and scripts that are
|
||||
not considered "core". This keeps the core simpler, and allows you to enhance
|
||||
gitolite for your own purposes without too much fuss.
|
||||
gitolite for your own purposes without too much fuss. (As an extreme example,
|
||||
even mirroring is not in core now!)
|
||||
|
||||
(Also, please see the [developer notes][dev-notes] page).
|
||||
|
||||
## types of non-core programs
|
||||
|
||||
There are 5 basic types of non-core programs.
|
||||
|
||||
* *commands* can be run from the shell command line. Those listed in the
|
||||
COMMANDS hash of the rc file can also be run remotely.
|
||||
* *commands* can be run from the shell command line. Among those, the ones
|
||||
listed in the COMMANDS hash of the rc file can also be run remotely.
|
||||
* *hooks* are standard git hooks; see below.
|
||||
* *sugar scripts* change the conf language for your convenience. The word
|
||||
sugar comes from "syntactics sugar".
|
||||
sugar comes from "syntactic sugar".
|
||||
* *triggers* are to gitolite what hooks are to git. I just chose a
|
||||
different name to avoid confusion and constant disambiguation in the docs.
|
||||
* **VREFs** are extensions to the access control check part of gitolite.
|
||||
|
|
@ -22,7 +25,7 @@ some description of each.
|
|||
|
||||
## #commands gitolite "commands"
|
||||
|
||||
Gitolite comes with several commands that users can run. Remote user run the
|
||||
Gitolite comes with several commands that users can run. Remote users run the
|
||||
commands by saying:
|
||||
|
||||
ssh git@host command-name [args...]
|
||||
|
|
@ -56,8 +59,8 @@ The rest is between you and 'man githooks' :-)
|
|||
## #sugar syntactic sugar
|
||||
|
||||
Sugar scripts help you change the perceived syntax of the conf language. The
|
||||
base syntax of the language is as described [here][conf], so sugar scripts
|
||||
take something *else* and convert it into that.
|
||||
base syntax of the language is very simple, so sugar scripts take something
|
||||
*else* and convert it into that.
|
||||
|
||||
That way, the admin sees additional features (like allowing continuation
|
||||
lines), while the parser in the core gitolite engine does not change.
|
||||
|
|
|
|||
114
doc/deleg.mkd
Normal file
114
doc/deleg.mkd
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
# delegating access control responsibilities
|
||||
|
||||
Delegation allows you to divide up a large conf file into smaller groups of
|
||||
repos (called **subconf**s) and hand over responsibility to manage them to
|
||||
**sub-admin**s. Gitolite can prevent one sub-admin from being able to set
|
||||
access rules for any other sub-admin's repos.
|
||||
|
||||
Delegation is achieved by combining two gitolite features: [subconf][] and the
|
||||
[NAME VREF][NAME].
|
||||
|
||||
To understand delegation, read both those links then come back to this
|
||||
example.
|
||||
|
||||
## example
|
||||
|
||||
@webbrowsers = firefox lynx browsers/..*
|
||||
@webservers = apache nginx servers/..*
|
||||
@malwares = conficker storm ms/..*
|
||||
# side note: if anyone objects, we claim ms stands for "metasploit" ;-)
|
||||
|
||||
# the admin repo access was probably like this to start with:
|
||||
repo gitolite-admin
|
||||
RW+ = sitaram
|
||||
# now add these lines to the config for the admin repo
|
||||
RW = alice bob mallory
|
||||
RW VREF/NAME/conf/subs/webbrowsers = alice
|
||||
RW VREF/NAME/conf/subs/webservers = bob
|
||||
RW VREF/NAME/conf/subs/malwares = mallory
|
||||
- VREF/NAME/ = alice bob mallory
|
||||
|
||||
Finally, you tell gitolite to pull in these files using the "subconf" command
|
||||
|
||||
subconf "subs/*.conf"
|
||||
|
||||
And that's it.
|
||||
|
||||
## #subconf the subconf command
|
||||
|
||||
Subconf is exactly like the include command in syntax:
|
||||
|
||||
subconf "foo/bar.conf"
|
||||
|
||||
but while reading the included file, it sets a "subconf name" of "foo".
|
||||
|
||||
When a subconf name is in effect, there are some restrictions on what repos
|
||||
can be managed.
|
||||
|
||||
For example, in the include file in the above example, you can only have
|
||||
"repo" lines for:
|
||||
|
||||
* a repo called "foo"
|
||||
* a group called "@foo" defined outside the include file
|
||||
* a member of a group called "@foo" (again, defined outside)
|
||||
* a repo that matches a member of a group called "@foo" if that member is a
|
||||
regular expression pattern
|
||||
|
||||
Here's an example. If the main conf file contains
|
||||
|
||||
@foo = aa bb cc/..*
|
||||
|
||||
then the subconf can only accept repo statements that refer to 'foo', '@foo',
|
||||
'aa', 'bb', or any repo whose name starts with 'cc/'.
|
||||
|
||||
### how the "subconf name" is derived
|
||||
|
||||
For subconf lines that look just like include statements, i.e.,
|
||||
|
||||
subconf "foo/bar.conf"
|
||||
subconf "frob/*.conf"
|
||||
# assume frob has files aa.conf, bb.conf
|
||||
|
||||
the subconf name as each file is being processed is the base name of the file.
|
||||
This means it would be "bar" for the first line, "aa" when processing
|
||||
"frob/aa.conf", and "bb" when processing "frob/bb.conf".
|
||||
|
||||
A variation of subconf exists that can explicitly state the subconf name:
|
||||
|
||||
subconf foo "frob/*.conf"
|
||||
|
||||
In this variation, regardless of what file in "frob/" is being read, the
|
||||
subconf name in effect is "foo".
|
||||
|
||||
## security notes
|
||||
|
||||
### group names
|
||||
|
||||
You can use "@group"s defined in the main config file but do not attempt to
|
||||
redefine or extend them in your own subconf file. If you must extend a group
|
||||
(say `@foo`) defined in the main config file, do this:
|
||||
|
||||
@myfoo = @foo
|
||||
# now do whatever you want with @myfoo
|
||||
|
||||
Group names you define in your subconf will not clash even if the exact same
|
||||
name is used in another subconf file, so you need not worry about that.
|
||||
|
||||
### delegating pubkeys
|
||||
|
||||
Short answer: not gonna happen.
|
||||
|
||||
The delegation feature is meant only for access control rules, not pubkeys.
|
||||
Adding/removing pubkeys is a much more significant event than changing branch
|
||||
level permissions for people already on staff, and only the main admin should
|
||||
be allowed to do it.
|
||||
|
||||
Gitolite's "userids" all live in the same namespace. This is unlikely to
|
||||
change, so please don't ask -- it gets real complicated to do otherwise.
|
||||
Allowing sub-admins to add users means username collisions, which also means
|
||||
security problems (admin-A creates a pubkey for Admin-B, thus gaining access
|
||||
to all of Admin-B's stuff).
|
||||
|
||||
If you feel the need to delegate even that, please just go the whole hog and
|
||||
give them separate gitolite instances (i.e., running under different gitolite
|
||||
hosting users)!
|
||||
|
|
@ -3,9 +3,6 @@
|
|||
Gitolite has a huge bunch of existing features that gradually need to moved
|
||||
over. Plus you may want to write your own programs to interact with it.
|
||||
|
||||
Hints for developers wishing to help migrate features over from g2 are
|
||||
[here][dev-hints].
|
||||
|
||||
Here are some random notes on developing hooks, commands, triggers, and sugar
|
||||
scripts.
|
||||
|
||||
|
|
@ -20,15 +17,15 @@ In general, the following environment variables should always be available:
|
|||
Commands invoked by a remote client will also have `GL_USER` set. Hooks will
|
||||
have `GL_REPO` also set.
|
||||
|
||||
Finally, note that triggers get a lot of relevant information as arguments;
|
||||
see [here][triggers] for details.
|
||||
Finally, note that triggers get a lot of relevant information from gitolite as
|
||||
arguments; see [here][triggers] for details.
|
||||
|
||||
## APIs
|
||||
|
||||
### the shell API
|
||||
|
||||
The following commands exist to help you write shell scripts that interact
|
||||
easily with gitolite. Each of them responds to `h` so please run that for
|
||||
easily with gitolite. Each of them responds to `-h` so please run that for
|
||||
more info.
|
||||
|
||||
* `gitolite access` to check access rights given repo, user, type of access
|
||||
|
|
@ -38,7 +35,7 @@ more info.
|
|||
src/commands/desc
|
||||
|
||||
* `gitolite git-config` to check gitolite options or git config variables
|
||||
directly from gitolite's "compiled output, (i.e., without looking at the
|
||||
directly from gitolite's "compiled" output, (i.e., without looking at the
|
||||
actual `repo.git/config` file or using the `git config` command). Example
|
||||
use: none yet
|
||||
|
||||
|
|
@ -53,16 +50,18 @@ perl API module) for ideas.
|
|||
...is implemented by Gitolite::Easy; the comments in src/Gitolite/Easy.pm
|
||||
serve as documentation.
|
||||
|
||||
## your own hooks
|
||||
## writing your own...
|
||||
|
||||
### anything but the update hook
|
||||
### ...hooks
|
||||
|
||||
#### anything but the update hook
|
||||
|
||||
If you want to add your own hook, it's easy as long as it's not the 'update'
|
||||
hook. Just add it to `$HOME/.gitolite/hooks/common` and run `gitolite setup`.
|
||||
|
||||
The rest is between you and 'man githooks' :-)
|
||||
|
||||
### update hook
|
||||
#### update hook
|
||||
|
||||
If you want to add additional `update` hook functionality, do this:
|
||||
|
||||
|
|
@ -83,7 +82,7 @@ Note: a normal update hook expects 3 arguments (ref, old SHA, new SHA). A
|
|||
VREF will get those three, followed by at least 4 more. Your VREF should just
|
||||
ignore the extra args.
|
||||
|
||||
## your own commands
|
||||
### ...commands
|
||||
|
||||
You can add your own commands. You can run them on the server (example,
|
||||
`gitolite access`). Then you can enable certain commands to be allowed to run
|
||||
|
|
@ -94,19 +93,15 @@ receive the arguments you append. In addition, the env var `GL_USER` is
|
|||
available if it is being run remotely. src/commands/desc is the best example
|
||||
at present.
|
||||
|
||||
## your own trigger programs
|
||||
### ...trigger programs
|
||||
|
||||
Trigger programs are just commands whose names have been added to the
|
||||
appropriate list in the [rc][] file. Triggers get specific arguments
|
||||
depending on when they are called; see [here][triggers] for details.
|
||||
Trigger programs run at specific points in gitolite's execution, with specific
|
||||
arguments being passed to them. See the [triggers][] page for details.
|
||||
|
||||
You can write programs that are both manually runnable as well as callable by
|
||||
trigger events, especially if they don't *need* any arguments.
|
||||
|
||||
Look in the distributed [rc][] file for example programs; at this point there
|
||||
aren't many.
|
||||
|
||||
## your own "sugar"
|
||||
### ..."sugar"
|
||||
|
||||
Syntactic sugar helpers are NOT complete, standalone, programs. They must
|
||||
include a perl sub called `sugar_script` that takes in a listref, and returns
|
||||
|
|
|
|||
|
|
@ -2,20 +2,19 @@
|
|||
|
||||
Not yet done (will be tackled in this order unless someone asks):
|
||||
|
||||
* detailed documentation for new features
|
||||
* querying the outside world for group info (see gl-get-membership-program
|
||||
in g2)
|
||||
* mirroring
|
||||
* svnserve (someone is testing it)
|
||||
* pulling in documentation for things that are the same in g2
|
||||
* "unrestricted arguments" for some ADCs (like git-annexe)
|
||||
* smart http
|
||||
* special features (no-create-repos, shell-access, gl-all-read-all, etc)
|
||||
* special features (no-create-repos, gl-all-read-all, etc)
|
||||
* mechanism for ADCs using unchecked arguments -- this is not just a matter
|
||||
of writing it; I have to think about *how* it will be done. (AFAIK the
|
||||
only tool affected is git-annexe)
|
||||
|
||||
Help needed:
|
||||
|
||||
* I'd like distro packagers to play with it and help with migration advice
|
||||
for distro-upgrades
|
||||
* [rsync][pw2], htpasswd
|
||||
* rsync, htpasswd
|
||||
* git-annexe support (but this has a pre-requisite in the previous list)
|
||||
|
||||
Won't be done unless someone asks (saw no evidence that anyone used them in g2
|
||||
|
|
@ -30,6 +29,7 @@ Done:
|
|||
|
||||
* core code
|
||||
* test suite
|
||||
* some documentation
|
||||
* mirroring
|
||||
* most documentation
|
||||
* distro packaging instructions
|
||||
* migration advice for common cases
|
||||
|
|
|
|||
190
doc/emergencies.mkd
Normal file
190
doc/emergencies.mkd
Normal file
|
|
@ -0,0 +1,190 @@
|
|||
# help for emergencies
|
||||
|
||||
----
|
||||
|
||||
"Don't Panic!"
|
||||
|
||||
----
|
||||
|
||||
## #lost-key lost admin key/access
|
||||
|
||||
If you lost your gitolite **admin** key or access, here's what you do. We'll
|
||||
assume your username is 'alice'.
|
||||
|
||||
* Make yourself a new keypair and copy the public key to the server as
|
||||
'alice.pub'.
|
||||
|
||||
* Log on to the server, and run `gitolite setup -pk alice.pub`.
|
||||
|
||||
That's it; the new alice.pub file replaces whatever existed in the repo
|
||||
before.
|
||||
|
||||
## #bypass bypassing gitolite
|
||||
|
||||
You may have lost access because of a conf file error, in which case the above
|
||||
trick won't help. What you want is to make changes to the repo (or perhaps
|
||||
just rewind) and push that. Here's how to do that:
|
||||
|
||||
* Log on to the server.
|
||||
|
||||
* Clone the admin repo using the full path: `git clone
|
||||
$HOME/repositories/gitolite-admin.git temp`.
|
||||
|
||||
* Make whatever changes you want -- add/replace a key, 'git revert' or 'git
|
||||
reset --hard' to an older commit, etc. Anything you need to fix the
|
||||
problem, really.
|
||||
|
||||
* Run `gitolite push` (or possibly `gitolite push -f`). Note that's
|
||||
'gitolite push', not 'git push'.
|
||||
|
||||
<font color="red">
|
||||
**NOTE**: gitolite does **no access checking** when you do this!
|
||||
</font>
|
||||
|
||||
## #clean cleaning out a botched install
|
||||
|
||||
If you've read the [files involved in gitolite][files] page, you probably know
|
||||
the answer, but here's a list of files you should blow away.
|
||||
|
||||
* **gitolite sources** -- can be found by running `which gitolite`. If it's
|
||||
a symlink, go to its target directory.
|
||||
|
||||
* **gitolite admin directory** -- `$HOME/.gitolite`. Save the 'logs'
|
||||
directory if you want to preserve them for any reason.
|
||||
|
||||
* **the rc file** -- `$HOME/.gitolite.rc`. If you made any changes to it
|
||||
you can save it as some other name instead of deleting it.
|
||||
|
||||
* **the gitolite-admin repo** -- `$HOME/repositories/gitolite-admin.git`.
|
||||
You can clone it somewhere to save it before blowing it away if you wish.
|
||||
|
||||
* **git repositories** -- `$HOME/repositories`. The install process will
|
||||
not touch any existing repos except 'gitolite-admin.git', so you do not
|
||||
have to blow away (or move) your work repos to fix a botched install.
|
||||
|
||||
Only when you update the conf to include those repos and push the changes
|
||||
will those repos be touched. And even then all that happens is that the
|
||||
update hook, if any, is replaced with gitolite's own hook.
|
||||
|
||||
* **ssh stuff** -- exercise caution when doing this, but in general it
|
||||
should be safe to delete all lines between the "gitolite start" and
|
||||
"gitolite end" markers in `$HOME/.ssh/authorized_keys`.
|
||||
|
||||
Gitolite does not touch any other files in the ssh directory.
|
||||
|
||||
## #ce common errors
|
||||
|
||||
* `WARNING: keydir/<yourname>.pub duplicates a non-gitolite key, sshd will ignore it`
|
||||
|
||||
You used a key that is already set to give you shell access. You cannot
|
||||
use the same key to get shell access as well as access gitolite repos.
|
||||
|
||||
Solution: use a different keypair for gitolite. There's a slightly longer
|
||||
discussion in the [setup][] page. Also see [why bypassing causes a
|
||||
problem][ybpfail] and both the documents in [ssh][] for background.
|
||||
|
||||
* `Empty compile time value given to use lib at hooks/update line 6`
|
||||
|
||||
(followed by `Can't locate Gitolite/Hooks/Update.pm in @INC` a couple of
|
||||
lines later).
|
||||
|
||||
You're bypassing gitolite. You cloned the repo using the full path (i.e.,
|
||||
including the `repositories/` prefix), either directly on the server, or
|
||||
via ssh but with a key that gives you **shell** access.
|
||||
|
||||
Solution: same as for the previous bullet.
|
||||
|
||||
NOTE: If you really *must* do it, and this is a one-time thing, you can
|
||||
try `gitolite push` instead of `git push`. **BUT**... this defeats all
|
||||
gitolite access control, so if you're going to do this often, maybe you
|
||||
don't need gitolite!
|
||||
|
||||
## #ue uncommon errors
|
||||
|
||||
* `WARNING: split conf not set, gl-conf present for <repo>`
|
||||
|
||||
(case 1) This can happen if you have a *bare* repo (i.e., some `repo.git`
|
||||
directory) copied from g2 with `GL_BIG_CONFIG` on, and you pushed a change
|
||||
to the conf or ran certain commands *before* adding the newly added repo
|
||||
to the conf file.
|
||||
|
||||
(case 2) This can also happen if you changed something like this
|
||||
|
||||
repo foo
|
||||
...<some rules>...
|
||||
|
||||
to this
|
||||
|
||||
@grp = foo
|
||||
repo @grp
|
||||
...<some rules>...
|
||||
|
||||
Also, even running `gitolite setup` will not fix this.
|
||||
|
||||
The root cause is an internal consistency check that I do not wish to
|
||||
disable or subvert. It is there for a reason, and I would prefer a
|
||||
warning that a human can investigate.
|
||||
|
||||
If you're sure the reasons are one of the two above, you can either add
|
||||
the repo to the conf file in case 1, or manually remove the gl-conf file
|
||||
from the repo.git directory in case 2.
|
||||
|
||||
Either way, run `gitolite setup` afterwards to make sure things are in
|
||||
good shape.
|
||||
|
||||
If you think neither of those is the cause, email me.
|
||||
|
||||
## #ngp things that are not gitolite problems
|
||||
|
||||
There are several things that appear to be gitolite problems but are not. I
|
||||
cannot help with most of these (although the good folks on irc or the mailing
|
||||
list -- see [contact][] -- might be able to; they certainly appear to have a
|
||||
lot more patience than I do, bless 'em!)
|
||||
|
||||
* **client side software**
|
||||
|
||||
* putty/plink
|
||||
* jgit/Eclipse
|
||||
* Mac OS client **or** server
|
||||
* putty/plink
|
||||
* windows as a server
|
||||
* ...probably some more I forgot; will update this list as I remember...
|
||||
* did I mention putty/plink?
|
||||
|
||||
* **ssh**
|
||||
|
||||
The *superstar* of the "not a gitolite problem" category is actually ssh.
|
||||
|
||||
Surprised? It is so common that it has [its own document][auth] to tell
|
||||
you why it is *not* a gitolite problem, while [another one][ssh] tries to
|
||||
help you anyway!
|
||||
|
||||
Everything I know is in that latter link. Please email me about ssh ONLY
|
||||
if you find something wrong or missing in those documents.
|
||||
|
||||
* **git**
|
||||
|
||||
I wish I had a dollar for each time someone did a *first push* on a new
|
||||
repo, got an error because there were "no refs in common (etc.)", and
|
||||
asked me why gitolite was not allowing the push.
|
||||
|
||||
Gitolite is designed to look like just another bare repo server to a
|
||||
client (except requiring public keys -- no passwords allowed). It is
|
||||
*completely transparent* when there is no authorisation failure (i.e.,
|
||||
when the access is allowed, the remote client has no way of knowing
|
||||
gitolite was even installed!)
|
||||
|
||||
Even "on disk", apart from reserving the `update` hook for itself,
|
||||
gitolite does nothing to your bare repos unless you tell it to (for
|
||||
example, adding 'gitweb.owner' and such to the config file).
|
||||
|
||||
BEFORE you think gitolite is the problem, try the same thing with a normal
|
||||
bare repo. In most cases you can play with it just by doing something
|
||||
like this:
|
||||
|
||||
mkdir /tmp/throwaway
|
||||
cd /tmp/throwaway
|
||||
git clone --mirror <some repo you have a URL for> bare.git
|
||||
git clone bare.git worktree
|
||||
cd worktree
|
||||
<...try stuff>
|
||||
71
doc/external.mkd
Normal file
71
doc/external.mkd
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
# interfacing with external tools
|
||||
|
||||
> ----
|
||||
|
||||
> **Note**: The old gitolite (v1.x, v2.x) used to tie itself into knots
|
||||
> dealing with gitweb and daemon. One of the goals of g3 was to get out of
|
||||
> that game, which your author does not play anyway. This means statements
|
||||
> like "...special user called 'gitweb'..." really apply to the [non-core][]
|
||||
> programs that gitolite ships with, not to "core" gitolite, and any or all
|
||||
> of this functionality can be disabled by commenting out certain lines in
|
||||
> the [rc][] file.
|
||||
|
||||
> ----
|
||||
|
||||
> Also, **note** that gitolite does **not** install or configure
|
||||
> gitweb/git-daemon -- that is a one-time setup you must do separately.
|
||||
|
||||
> ----
|
||||
|
||||
## gitweb
|
||||
|
||||
The following repos are deemed to be readable by gitweb:
|
||||
|
||||
* any repos readable by the special user `gitweb`
|
||||
* any repos containing one or more of the following types of lines:
|
||||
|
||||
config gitweb.owner = owner name
|
||||
config gitweb.description = some description
|
||||
config gitweb.category = some category
|
||||
|
||||
Side note: the following shorter forms are available as [syntactic
|
||||
sugar][sugar] for the above longer forms:
|
||||
|
||||
owner = owner name
|
||||
desc = some description
|
||||
category = some category
|
||||
|
||||
The list of gitweb-readable repos is written to a file whose name is given by
|
||||
the [rc][] file variable `GITWEB_PROJECTS_LIST`. The default value of this
|
||||
variable, if it is not specified or empty, is `$HOME/projects.list`.
|
||||
|
||||
In addition, each of the config variables described above is written to the
|
||||
repo to which it pertains, so that gitweb can use them.
|
||||
|
||||
### #umask changing the UMASK
|
||||
|
||||
Gitweb typically runs under a different userid, and the default permissions
|
||||
that gitolite sets make them unreadable.
|
||||
|
||||
See the section on the `UMASK` variable in the documentation for the [rc
|
||||
file][rc].
|
||||
|
||||
## git-daemon
|
||||
|
||||
Any repo readable by the special user `daemon` is deemed to be readable by
|
||||
git-daemon. For each of these repos, an empty file called
|
||||
`git-daemon-export-ok` is created in the repository (i.e., the `repo.git`
|
||||
directory inside `$HOME/repositories`).
|
||||
|
||||
## tips
|
||||
|
||||
Setting descriptions en-masse usually does not make sense, but you can
|
||||
certainly do things like
|
||||
|
||||
repo @all
|
||||
R = gitweb daemon
|
||||
|
||||
assuming you have other means of setting 'gitweb.description' and
|
||||
'gitweb.owner'.
|
||||
|
||||
Also see [this][deny-rules] for a twist on that.
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
This document will explain why an "ssh issue" is almost never a "gitolite
|
||||
issue", and, indirectly, why I dont get too excited about the former.
|
||||
|
||||
Note: for actual ssh troubleshooting see [this][ssh-troubleshooting].
|
||||
Note: for actual ssh troubleshooting see [this][sts].
|
||||
|
||||
Here is a fundamental point: <font color="red">**Gitolite does not do
|
||||
authentication. It only does authorisation**.</font>
|
||||
|
|
@ -18,41 +18,42 @@ So first, let's loosely define these words:
|
|||
> **Authorisation** is the process of asking what you want to do and
|
||||
> deciding if you're allowed to do it or not.
|
||||
|
||||
Now, if you managed to read about [gitolite and ssh][gitolite-and-ssh], you
|
||||
Now, if you managed to read about [gitolite and ssh][glssh], you
|
||||
know that gitolite is meant to be invoked as:
|
||||
|
||||
/full/path/to/gl-auth-command some-authenticated-gitolite-username
|
||||
/full/path/to/gitolite-shell some-authenticated-gitolite-username
|
||||
|
||||
(where the "gitolite username" is a "virtual" username; it does not have to
|
||||
be, and usually *isn't*, an actual *unix* username).
|
||||
|
||||
As you can see, authentication happens before gitolite is called.
|
||||
|
||||
## but... but... you have all that ssh stuff in there!
|
||||
## but... but... you have all that ssh stuff in gitolite!
|
||||
|
||||
The default mode of using gitolite does use ssh keys, but all it's doing is
|
||||
helping you **setup** ssh-based authentication **as a convenience to you**.
|
||||
No I don't. Not in "core" gitolite from g3 onwards :-)
|
||||
|
||||
You don't have to use it, though. And many people don't. The examples I know
|
||||
are [smart http][http], and ldap-backed sshd. In both cases, gitolite has no
|
||||
role to play in creating users, setting up their passwords/keys, etc. There's
|
||||
even a `GL_NO_SETUP_AUTHKEYS` option to make sure gitolite doesn't meddle with
|
||||
the authkeys file in such installations.
|
||||
The default setup does use ssh keys, but it's only helping you **setup**
|
||||
ssh-based authentication **as a convenience to you**. But in fact it is a
|
||||
*completely* separate program that you can disable (in the rc file) or replace
|
||||
with something else of your choice.
|
||||
|
||||
For example, in both [smart http][http] and ldap-backed sshd, gitolite has no
|
||||
role to play in creating users, setting up their passwords/keys, etc.
|
||||
|
||||
## so you're basically saying you won't support "X"
|
||||
|
||||
(where "X" is some ssh related behaviour change or feature)
|
||||
|
||||
Well, if it's not a security issue I *probably* won't. I'm willing to change
|
||||
my mind if enough people convince me they need it. (There's a mailing list if
|
||||
you want to find others who also need the same thing.)
|
||||
Well, if it's not a security issue I won't. But since it's no longer part of
|
||||
"core" gitolite, I can be much more relaxed about taking patches, or even
|
||||
alternative implementations.
|
||||
|
||||
While we're on the subject, locking someone out is *not* a security issue.
|
||||
Even if you locked yourself (the admin) out, the docs tell you how to recover
|
||||
Even if you [lost the admin key][lost-key], the docs tell you how to recover
|
||||
from such errors. You do need some password based method to get a shell
|
||||
command line on the server, of course.
|
||||
|
||||
## appendix: how to use other authentication systems with gitolite
|
||||
## #otherauth how to use other authentication systems with gitolite
|
||||
|
||||
The bottom line in terms of how to invoke gitolite has been described above,
|
||||
and as long as you manage to do that gitolite won't even know how the
|
||||
|
|
@ -84,6 +85,22 @@ to generate keypairs and send them to the admin, but they can be more
|
|||
centrally stored and perhaps used by other programs or tools simultaneously,
|
||||
which can be useful.
|
||||
|
||||
Finally, gitolite allows you to store *group* information externally too. See
|
||||
[here][ldap] for more on this.
|
||||
## #ldap getting user group info from LDAP
|
||||
|
||||
Gitolite's [groups][] are pretty convenient, but some organisations already
|
||||
have similar (or sufficient) information in their LDAP store.
|
||||
|
||||
Gitolite can tap into that information, with a little help. Write a program
|
||||
which, given a username, queries your LDAP store and returns a space-separated
|
||||
list of groups that the user is a member of. Then put the full path to this
|
||||
program in an [rc][] variable called `GROUPLIST_PGM`, like so:
|
||||
|
||||
GROUPLIST_PGM => '/home/git/bin/ldap-query-groups',
|
||||
|
||||
Now you can use those groupnames in access rules in gitolite, just as if you
|
||||
had declared their memberships in the conf file.
|
||||
|
||||
Caution: your program must do its own logging if you want the audit trail of
|
||||
"why/how did this user get access to this repo at this time?" to resolve
|
||||
properly. Gitolite does not do any logging of the results of the queries
|
||||
because for people who don't need it that would be a huge waste.
|
||||
|
|
|
|||
|
|
@ -99,13 +99,13 @@ The answer to the first question is the `command=` we talked about before. If
|
|||
you look in the `authorized_keys` file, you'll see entries like this (I chopped
|
||||
off the ends of course; they're pretty long lines):
|
||||
|
||||
command="[path]/gl-auth-command sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t...
|
||||
command="[path]/gl-auth-command usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
|
||||
command="[path]/gitolite-shell sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t...
|
||||
command="[path]/gitolite-shell usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
|
||||
|
||||
First, it finds out which of the public keys in this file match the incoming
|
||||
login. That's crypto stuff, and I won't go into it. Once the match has been
|
||||
found, it will run the command given on that line; e.g., if I logged in, it
|
||||
would run `[path]/gl-auth-command sitaram`. So the first thing to note is
|
||||
would run `[path]/gitolite-shell sitaram`. So the first thing to note is
|
||||
that such users do not get "shell access", which is good!
|
||||
|
||||
Before running the command, however, sshd sets up an environment variable
|
||||
|
|
@ -113,7 +113,7 @@ called `SSH_ORIGINAL_COMMAND` which contains the actual git command that your
|
|||
workstation sent out. This is the command that *would have run* if you did
|
||||
not have the `command=` part in the authorised keys file.
|
||||
|
||||
When `gl-auth-command` gets control, it looks at the first argument
|
||||
When `gitolite-shell` gets control, it looks at the first argument
|
||||
("sitaram", "usertwo", etc) to determine who you are. It then looks at the
|
||||
`SSH_ORIGINAL_COMMAND` variable to find out which repository you want to
|
||||
access, and whether you're reading or writing.
|
||||
|
|
|
|||
|
|
@ -1,64 +0,0 @@
|
|||
# not a gitolite problem
|
||||
|
||||
These are issues I do not want to be emailed about. That does not mean you
|
||||
cannot get help -- in all cases, you're welcome to ask on [irc or the mailing
|
||||
list][contact]. Irc especially has people with much more patience than I
|
||||
have, God bless them...
|
||||
|
||||
## specific clients, or specific server OSs
|
||||
|
||||
These are things I can not support. That does not mean they will not work
|
||||
with gitolite -- on the contrary, lots of people are using them.
|
||||
|
||||
But I personally don't use them, and I won't use them, and in my admittedly
|
||||
limited experience they have given me good reason to stay well away.
|
||||
|
||||
Please ask for help on the [mailing list or IRC][contact]. Please do not
|
||||
email me directly.
|
||||
|
||||
* putty/plink
|
||||
* jgit/Eclipse
|
||||
* Mac OS client or server
|
||||
* windows as a server
|
||||
* ...probably some more I forgot; will update this list as I remember...
|
||||
|
||||
## ssh
|
||||
|
||||
The *superstar* of the "not a gitolite problem" category is actually ssh.
|
||||
|
||||
Surprised? It is so common that it has [its own document][auth] to tell
|
||||
you why it is *not* a gitolite problem, while [another one][ssh] tries to
|
||||
help you anyway!
|
||||
|
||||
Everything I know is in that latter link. Please email me about ssh ONLY if
|
||||
you find something wrong or missing in those documents.
|
||||
|
||||
## git
|
||||
|
||||
Example 1: when a first `git push` to a new repo fails, it is not because of
|
||||
gitolite, it is because you need to say `git push origin master` or something.
|
||||
This is a git issue.
|
||||
|
||||
There are several such examples. Gitolite is designed to look like just
|
||||
another bare repo server to a client (except requiring public keys -- no
|
||||
passwords allowed). It is *completely transparent* when there is no
|
||||
authorisation failure (i.e., when the access is allowed, the remote client has
|
||||
no way of knowing gitolite was even installed!)
|
||||
|
||||
Even "on disk", apart from reserving the `update` hook for itself, gitolite
|
||||
does nothing to your bare repos unless you tell it to (for example, adding
|
||||
'gitweb.owner' and such to the config file).
|
||||
|
||||
BEFORE you think gitolite is a problem, try the same thing with a normal bare
|
||||
repo. In most cases you can play with it just by doing something like this:
|
||||
|
||||
mkdir /tmp/throwaway
|
||||
cd /tmp/throwaway
|
||||
git clone --mirror <some repo you have a URL for> bare.git
|
||||
git clone bare.git worktree
|
||||
cd worktree
|
||||
<...try stuff>
|
||||
|
||||
----
|
||||
|
||||
In addition, the original nagp has more funny stuff...
|
||||
203
doc/extras/putty.mkd
Normal file
203
doc/extras/putty.mkd
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
# putty and msysgit
|
||||
|
||||
This document is intended for those who wish to use Putty/Plink with msysgit.
|
||||
|
||||
If you need more help with putty or component programs I suggest looking at [the official putty documentation](http://the.earth.li/~sgtatham/putty/latest/htmldoc/).
|
||||
|
||||
**If you are not already using Putty for SSH it is recommended you do _NOT_ use it with msysgit.**
|
||||
|
||||
**Please note that this only covers the client side of things, and does not involve server side components to troubleshooting. For that, please see the [ssh-troubleshooting document][sts].**
|
||||
|
||||
<a name="msysgit_setup"/>
|
||||
|
||||
## msysgit setup
|
||||
|
||||
Provided you have putty sessions msysgit should give you the option of specifying a location to plink. If it did not then you will need to add an environment variable named "GIT\_SSH" to point at plink.exe, wherever you have that sitting.
|
||||
|
||||
How to do that on your version of windows will likely vary, and is not covered here. For purposes of example, on a 64 bit Windows Vista machine the GIT\_SSH value could be:
|
||||
|
||||
C:\Program Files (x86)\PuTTY\plink.exe
|
||||
|
||||
Note the lack of quotes.
|
||||
|
||||
Testing that msysgit is properly configured can be done from the git bash shell. Simply type (case sensitive, include the quotes):
|
||||
|
||||
"$GIT_SSH" -V
|
||||
|
||||
You should get a response similar to this:
|
||||
|
||||
plink: Release 0.60
|
||||
|
||||
If instead you get a "command not found" type error you likely have a typo in your environment variable.
|
||||
|
||||
<a name="Going_back_to_OpenSSH"/>
|
||||
|
||||
## Going back to OpenSSH
|
||||
|
||||
If you wish to go back to OpenSSH all you need to do is delete the GIT\_SSH environment variable. This will vary by your version of windows and thus is not covered here.
|
||||
|
||||
<a name="Putty_keys"/>
|
||||
|
||||
## Putty keys
|
||||
|
||||
If you do not already have putty private key files (.ppk) you will need to make at least one. You can either make a new one or convert an existing key to putty private key format.
|
||||
|
||||
Either way, you will want to use puttygen. Note that you can go the other way if you want to stop using putty but keep the key by exporting the key to OpenSSH format.
|
||||
|
||||
<a name="Creating_a_new_key"/>
|
||||
|
||||
### Creating a new key
|
||||
|
||||
To make it simple, I suggest SSH-2 RSA and a bit size of at least 1024. Larger keys will take longer to generate and will take longer to authenticate you on most systems. Making the key is as simple at hitting "Generate".
|
||||
|
||||
It is recommended to give the key a meaningful comment.
|
||||
|
||||
<a name="Importing_an_existing_key"/>
|
||||
|
||||
### Importing an existing key
|
||||
|
||||
If you already have an OpenSSH or ssh.com key you can import it using the "Import" option on the "Conversions" menu.
|
||||
|
||||
If the key does not have a meaningful comment I would suggest adding one at this point.
|
||||
|
||||
<a name="Loading_an_existing_key"/>
|
||||
|
||||
### Loading an existing key
|
||||
|
||||
If you need to load an existing key to edit or view it you can do so from the File menu.
|
||||
|
||||
<a name="Public_key"/>
|
||||
|
||||
### Public key
|
||||
|
||||
To get your public key for use with gitolite, load (or generate, or import) your key into puttygen. There is a box labeled "Public key for pasting into OpenSSH `authorized_keys` file" there. Copy the text into your preferred text editor and save.
|
||||
|
||||
<a name="Putty_ageant"/>
|
||||
|
||||
### Putty ageant
|
||||
|
||||
Though not required in all cases you may wish to use the putty ageant, pageant, to load your key(s). This will allow for your key(s) to be passphrase protected but not have to enter the passphrase when you go to use them, provided you have already loaded the key into the ageant.
|
||||
|
||||
<a name="Sessionless_or_raw_hostname_usage"/>
|
||||
|
||||
## Sessionless or raw hostname usage
|
||||
|
||||
When using plink without a putty session you pretty much have to load your keys with putty ageant, if only so that plink can find them.
|
||||
|
||||
<a name="Putty_sessions"/>
|
||||
|
||||
## Putty sessions
|
||||
|
||||
In addition to hostnames msysgit can, when using putty, use putty sessions. This works in a manner similar to definitions in OpenSSH's `ssh_config` file. All settings in the session that apply to plink usage will be loaded, including the key file to use and even the username to connect to. Thus, instead of:
|
||||
|
||||
ssh://user@host.example.ext:port/repo
|
||||
|
||||
You can use:
|
||||
|
||||
ssh://session_name/repo
|
||||
|
||||
<a name="Host_key_authentication"/>
|
||||
|
||||
## Host key authentication
|
||||
|
||||
Whether you are using hostnames or sessions you still run into one potential problem. Plink currently wants to validate the server's SSH host key before allowing you to connect, and when git calls plink there is no way to tell it yes. Thus, you may get something like this:
|
||||
|
||||
The server's host key is not cached in the registry. You
|
||||
have no guarantee that the server is the computer you
|
||||
think it is.
|
||||
The server's rsa2 key fingerprint is:
|
||||
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
|
||||
Connection abandoned.
|
||||
fatal: The remote end hung up unexpectedly
|
||||
|
||||
Or, in the case of the host key changing, something like this:
|
||||
|
||||
WARNING - POTENTIAL SECURITY BREACH!
|
||||
The server's host key does not match the one PuTTY has
|
||||
cached in the registry. This means that either the
|
||||
server administrator has changed the host key, or you
|
||||
have actually connected to another computer pretending
|
||||
to be the server.
|
||||
The new rsa2 key fingerprint is:
|
||||
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
|
||||
Connection abandoned.
|
||||
fatal: The remote end hung up unexpectedly
|
||||
|
||||
The solution is to call plink directly, or start putty and connect with it first. To use plink, open the Git Bash shell and enter:
|
||||
|
||||
"$GIT_SSH" hostname_or_session_name
|
||||
|
||||
When you do you will see something like this:
|
||||
|
||||
The server's host key is not cached in the registry. You
|
||||
have no guarantee that the server is the computer you
|
||||
think it is.
|
||||
The server's rsa2 key fingerprint is:
|
||||
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
|
||||
If you trust this host, enter "y" to add the key to
|
||||
PuTTY's cache and carry on connecting.
|
||||
If you want to carry on connecting just once, without
|
||||
adding the key to the cache, enter "n".
|
||||
If you do not trust this host, press Return to abandon the
|
||||
connection.
|
||||
Store key in cache? (y/n)
|
||||
|
||||
Or, in the case of a changed key, a response like this:
|
||||
|
||||
WARNING - POTENTIAL SECURITY BREACH!
|
||||
The server's host key does not match the one PuTTY has
|
||||
cached in the registry. This means that either the
|
||||
server administrator has changed the host key, or you
|
||||
have actually connected to another computer pretending
|
||||
to be the server.
|
||||
The new rsa2 key fingerprint is:
|
||||
ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
|
||||
If you were expecting this change and trust the new key,
|
||||
enter "y" to update PuTTY's cache and continue connecting.
|
||||
If you want to carry on connecting but without updating
|
||||
the cache, enter "n".
|
||||
If you want to abandon the connection completely, press
|
||||
Return to cancel. Pressing Return is the ONLY guaranteed
|
||||
safe choice.
|
||||
Update cached key? (y/n, Return cancels connection)
|
||||
|
||||
In either case hit y and the key will be stored.
|
||||
|
||||
<a name="Debugging_multiple_putty_ageant_keys"/>
|
||||
|
||||
## Debugging multiple putty ageant keys
|
||||
|
||||
In the event you are using putty ageant with multiple keys loaded you may see the wrong key being used. In general, pageant keys are tried in the order they were loaded into the ageant. If you have descriptive comment on each of your keys you can try connecting with plink in verbose mode to see what keys are being tried. Simply open the Git bash shell and run:
|
||||
|
||||
"$GIT_SSH" -v user@hostname
|
||||
|
||||
Or, if using sessions with a pre-entered username:
|
||||
|
||||
"$GIT_SSH" -v session_name
|
||||
|
||||
In either case, you should look for lines like:
|
||||
|
||||
Trying Pageant key #0
|
||||
Authenticating with public key "My Key" from agent
|
||||
|
||||
The first says which (numerical) key the ageant is trying. The second tells you the key comment for the authenticating key. To my knowledge the second line should only show up once, for the valid key.
|
||||
|
||||
<a name="Setperms_and_other_commands"/>
|
||||
|
||||
## Setperms and other commands
|
||||
|
||||
When using wildcard repos the setperms command is very important, and other commands can come in handy as well. See their documentation for how to use them, but where they use:
|
||||
|
||||
ssh user@host command etc etc
|
||||
|
||||
You will want to use:
|
||||
|
||||
"$GIT_SSH" user@host command etc etc
|
||||
|
||||
Otherwise everything should be identical.
|
||||
|
||||
<a name="About_this_document"/>
|
||||
|
||||
## About this document
|
||||
|
||||
This document was written by Thomas Berezansky (tsbere (at) mvlc (dot) org) in the hopes that it would be useful to those using putty on windows and wishing to use git/gitolite with their putty keys and sessions.
|
||||
|
|
@ -14,7 +14,7 @@ and accessing gitolite.
|
|||
* Before reading this document, it is **mandatory** to read and **completely
|
||||
understand** [this][ssh], which is a very detailed look at how gitolite
|
||||
uses ssh's features on the server side. Don't assume you know all that;
|
||||
if you knew it, you wouldn't be needing *this* document either!
|
||||
if you did, you wouldn't be needing *this* document either!
|
||||
|
||||
* This document, and others linked from this, together comprise all the help
|
||||
I can give you in terms of the ssh aspect of using gitolite. If you're
|
||||
|
|
@ -80,11 +80,6 @@ Here's how normal gitolite key handling works:
|
|||
between gitolite's "marker" lines (`# gitolite start` and `# gitolite
|
||||
end`).
|
||||
|
||||
### (Other resources)
|
||||
|
||||
People who think installing gitolite is too hard should take a look at this
|
||||
[tutorial][tut] to **see how simple it *actually* is**.
|
||||
|
||||
### common ssh problems
|
||||
|
||||
Since I'm pretty sure at least some of you didn't bother to read the
|
||||
|
|
@ -94,15 +89,16 @@ you there again. Especially the first bullet.
|
|||
Done? OK, read on...
|
||||
|
||||
The following problem(s) indicate that pubkey access is not working at all, so
|
||||
you should start with [appendix 1][stsapp1_]. If that doesn't fix the problem, continue
|
||||
you should start with [appendix 1][stsapp1]. If that doesn't fix the problem, continue
|
||||
with the other appendices in sequence.
|
||||
|
||||
* running any git clone/fetch/ls-remote or just `ssh git@server info` asks
|
||||
you for a password.
|
||||
|
||||
The following problem(s) indicate that your pubkey is bypassing gitolite and
|
||||
going straight to a shell. You should start with [appendix 2][stsapp2_] and continue with
|
||||
the rest in sequence. [Appendix 5][stsapp5_] has some background info.
|
||||
going straight to a shell. You should start with [appendix 2][sshkeys-lint]
|
||||
and continue with the rest in sequence. [Appendix 5][ybpfail] has some
|
||||
background info.
|
||||
|
||||
* running `ssh git@server info` gets you the output of the GNU 'info'
|
||||
command instead of gitolite's version and access info.
|
||||
|
|
@ -114,8 +110,8 @@ the rest in sequence. [Appendix 5][stsapp5_] has some background info.
|
|||
(note absence of `repositories/`)]
|
||||
|
||||
* you are able to clone repositories but are unable to push changes back
|
||||
(the error complains about the `GL_RC` environment variable not being set,
|
||||
and the `hooks/update` failing in some way).
|
||||
(the error complains about the `GL_BINDIR` environment variable not being
|
||||
set, and the `hooks/update` failing in some way).
|
||||
|
||||
[If you run `git remote -v` you will find that your clone URL included the
|
||||
`repositories/` described above!]
|
||||
|
|
@ -136,42 +132,39 @@ Done? OK, now the general outline for ssh troubleshooting is this:
|
|||
* make sure the server's overall setup even *allows* pubkey based login.
|
||||
I.e., check that git fetch/clone/ls-remote commands or a plain `ssh
|
||||
git@server info` do NOT ask for a password. If you do get asked for a
|
||||
password, see [appendix 1][stsapp1_].
|
||||
password, see [appendix 1][stsapp1].
|
||||
|
||||
* match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys
|
||||
file. To do this, run `sshkeys-lint`, which tells you in detail what key
|
||||
has what access. See [appendix 2][stsapp2_].
|
||||
has what access. See [appendix 2][sshkeys-lint].
|
||||
|
||||
* at this point, we know that we have the right key, and that if sshd
|
||||
receives that key, things will work. But we're not done yet. We still
|
||||
need to make sure that this specific key is being offered/sent by the
|
||||
client, instead of the default key. See [appendix 3][stsapp3_] and [appendix 4][sshhostaliases].
|
||||
client, instead of the default key. See [appendix 3][stsapp3] and
|
||||
[appendix 4][ssh-ha].
|
||||
|
||||
### random tips, tricks, and notes
|
||||
|
||||
#### giving shell access to gitolite users
|
||||
|
||||
We've managed (thanks to an idea from Jesse Keating) to make it possible for a
|
||||
single key to allow both gitolite access *and* shell access.
|
||||
Thanks to an idea from Jesse Keating, a single key can allow both gitolite
|
||||
access *and* shell access.
|
||||
|
||||
This is done by copying the pubkey (to which you want to give shell access) to
|
||||
the server and running
|
||||
This is done by manually prefixing the username with "-s" as an extra argument
|
||||
in the "command=" part of `~/.ssh/authorized_keys`. For example
|
||||
|
||||
gl-tool add-shell-user ~/foo.pub
|
||||
command="/home/g3/gitolite/src/gitolite-shell u1",no-port-[...etc...]
|
||||
|
||||
**IMPORTANT UPGRADE NOTE**: previous implementations of this feature were
|
||||
crap. There was no easy/elegant way to ensure that someone who had repo admin
|
||||
access would not manage to get himself shell access.
|
||||
should be edited to be
|
||||
|
||||
Giving someone shell access requires that you should have shell access in the
|
||||
first place, so the simplest way is to enable it from the server side only.
|
||||
command="/home/g3/gitolite/src/gitolite-shell -s u1",no-port-[...etc...]
|
||||
|
||||
#### losing your admin key
|
||||
and moved out of the gitolite area of the authkeys file.
|
||||
|
||||
If you lost the admin key, and need to re-establish ownership of the
|
||||
gitolite-admin repository with a fresh key, get a shell on the server and use
|
||||
the program called `gl-admin-push` that comes with gitolite. See instructions
|
||||
[here][adminpush].
|
||||
It should be easy to make src/triggers/post-compile/ssh-authkeys read a list
|
||||
of shell capable users from some file on the server and put in the "-s" for
|
||||
those users. Patches welcome.
|
||||
|
||||
#### simulating ssh-copy-id
|
||||
|
||||
|
|
@ -199,11 +192,12 @@ bigger problems than gitolite install not working!)]
|
|||
#### problems with using non-openssh public keys
|
||||
|
||||
Gitolite accepts public keys only in openssh format. Trying to use an "ssh2"
|
||||
key (used by proprietary SSH software) results in:
|
||||
key (used by proprietary SSH software) will not be a happy experience.
|
||||
src/triggers/post-compile/ssh-authkeys can be made to detect non-openssh
|
||||
formats and automatically convert them; patches welcome!
|
||||
|
||||
WARNING: a pubkey file can only have one line (key); ignoring YourName.pub
|
||||
|
||||
To convert ssh2-compatible keys to openssh run:
|
||||
The actual conversion command, if you want to just do it manually for now and
|
||||
be done with it, is:
|
||||
|
||||
ssh-keygen -i -f /tmp/ssh2/YourName.pub > /tmp/openssh/YourName.pub
|
||||
|
||||
|
|
@ -218,9 +212,9 @@ used them for any kind of git access). If you have unusual ssh problems that
|
|||
just don't seem to have any explanation, try removing all traces of
|
||||
putty/plink, including environment variables, etc., and then try again.
|
||||
|
||||
Thankfully, someone contributed [contrib/putty.mkd][contrib_putty].
|
||||
Thankfully, someone contributed [this][putty].
|
||||
|
||||
### #stsapp1_ appendix 1: ssh daemon asks for a password
|
||||
### #stsapp1 appendix 1: ssh daemon asks for a password
|
||||
|
||||
> **NOTE**: This section should be useful to anyone trying to get
|
||||
> password-less access working. It is not necessarily specific to gitolite,
|
||||
|
|
@ -231,7 +225,7 @@ You have generated a keypair on your workstation (`ssh-keygen`) and copied the
|
|||
public part of it (`~/.ssh/id_rsa.pub`, by default) to the server.
|
||||
|
||||
On the server you have appended this file to `~/.ssh/authorized_keys`. Or you
|
||||
ran something, like the `gl-setup` step during a gitolite install, which
|
||||
ran something, like the `gitolite setup` step during a gitolite install, which
|
||||
should have done that for you.
|
||||
|
||||
You now expect to log in without having to type in a password, but when you
|
||||
|
|
@ -280,6 +274,10 @@ This is a quick checklist:
|
|||
`AllowUsers` config entry, then only users mentioned in that line are
|
||||
allowed to log in!
|
||||
|
||||
* while you're in there, check that file does NOT have a setting for
|
||||
`AuthorizedKeysFile`. See `man sshd_config` for details. This setting is
|
||||
a show stopper for gitolite to use ssh.
|
||||
|
||||
* some OSs/distributions require that the "git" user should have a password
|
||||
and/or not be a locked account. You may want to check that as well.
|
||||
|
||||
|
|
@ -288,27 +286,27 @@ This is a quick checklist:
|
|||
this file for messages matching the approximate time of your last attempt
|
||||
to login, to see if they tell you what is the problem.
|
||||
|
||||
### #stsapp2_ appendix 2: which key is which -- running sshkeys-lint
|
||||
### #sshkeys-lint appendix 2: which key is which -- running sshkeys-lint
|
||||
|
||||
Follow these steps on the client:
|
||||
The sshkeys-lint program can be run on the server or the client. Run it with
|
||||
'-h' to get a help message.
|
||||
|
||||
On the server you can run `gitolite sshkeys-lint` and it will tell you, for
|
||||
each key in the admin directory's keydir, what access is available. This is
|
||||
especially good at finding duplicate keys and such.
|
||||
|
||||
To run it on the client you have to copy the file src/commands/sshkeys-lint
|
||||
from some gitolite clone, then follow these steps:
|
||||
|
||||
* get a copy of `~/.ssh/authorized_keys` from the server and put it in
|
||||
`/tmp/foo` or something
|
||||
|
||||
* cd to `~/.ssh`
|
||||
|
||||
* run `sshkeys-lint *.pub < /tmp/foo`
|
||||
* run `/path/to/sshkeys-lint *.pub < /tmp/foo`
|
||||
|
||||
This tells you, for each pubkey, what type of access (if any) it has to the
|
||||
server.
|
||||
|
||||
Note that it is not trying to log in or anything -- it's just comparing bits
|
||||
of text (the contents of STDIN taken as an authkeys file, and the contents of
|
||||
each of the `*.pub` files one by one).
|
||||
|
||||
> Note: It's also a stand-alone program, so even if your gitolite version is
|
||||
> old, you can safely bring over just this program from a more recent
|
||||
> gitolite and use it, without having to upgrade gitolite itself.
|
||||
Note that it is not trying to log in or anything -- it's just comparing
|
||||
fingerprints as computed by `ssh-keygen -l`.
|
||||
|
||||
If the pubkey file you're interested in appears to have the correct access to
|
||||
the server, you're done with this step.
|
||||
|
|
@ -327,7 +325,7 @@ need. Be careful:
|
|||
|
||||
The admin often has passwordless shell access to `git@server` already, and
|
||||
then used that same key to get access to gitolite (i.e., copied that same
|
||||
pubkey as YourName.pub and ran `gl-setup` on it).
|
||||
pubkey as YourName.pub and ran `gitolite setup` on it).
|
||||
|
||||
As a result, the same key appears twice in the authkeys file now, and since
|
||||
the ssh server will always use the first match, the second occurrence (which
|
||||
|
|
@ -335,11 +333,11 @@ invokes gitolite) is ignored.
|
|||
|
||||
To fix this, you have to use a different keypair for gitolite access. The
|
||||
best way to do this is to create a new keypair, copy the pubkey to the server
|
||||
as YourName.pub, then run `gl-setup YourName.pub` on the server. Remember to
|
||||
adjust your agent identities using ssh-add -D and ssh-add if you're using
|
||||
ssh-agent, otherwise these new keys may not work.
|
||||
as YourName.pub, then run `gitolite setup -pk YourName.pub` on the server.
|
||||
Remember to adjust your agent identities using ssh-add -D and ssh-add if
|
||||
you're using ssh-agent, otherwise these new keys may not work.
|
||||
|
||||
### #stsapp3_ appendix 3: ssh client may not be offering the right key
|
||||
### #stsapp3 appendix 3: ssh client may not be offering the right key
|
||||
|
||||
* make sure the right private key is being offered. Run ssh in very
|
||||
verbose mode and look for the word "Offering", like so:
|
||||
|
|
@ -348,7 +346,7 @@ ssh-agent, otherwise these new keys may not work.
|
|||
|
||||
If some keys *are* being offered, but not the key that was supposed to be
|
||||
used, you may be using ssh-agent (next bullet). You may also need to
|
||||
create some host aliases in `~/.ssh/config` ([appendix 4][sshhostaliases]).
|
||||
create some host aliases in `~/.ssh/config` ([appendix 4][ssh-ha]).
|
||||
|
||||
* (ssh-agent issues) If `ssh-add -l` responds with either "The agent has no
|
||||
identities." or "Could not open a connection to your authentication
|
||||
|
|
@ -361,7 +359,7 @@ ssh-agent, otherwise these new keys may not work.
|
|||
In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try
|
||||
the access again.
|
||||
|
||||
### F=sshhostaliases appendix 4: host aliases
|
||||
### #ssh-ha appendix 4: ssh host aliases
|
||||
|
||||
(or "making git use the right options for ssh")
|
||||
|
||||
|
|
@ -397,10 +395,10 @@ way to do this, as far as I know.
|
|||
|
||||
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
|
||||
|
||||
### #stsapp5_ appendix 5: why bypassing gitolite causes a problem
|
||||
### #ybpfail appendix 5: why bypassing gitolite causes a problem
|
||||
|
||||
When you bypass gitolite, you end up running your normal shell instead of the
|
||||
special gitolite entry point script `gl-auth-command`.
|
||||
special gitolite entry point script `gitolite-shell`.
|
||||
|
||||
This means commands (like 'info') are interpreted by the shell instead of
|
||||
gitolite.
|
||||
|
|
|
|||
|
|
@ -2,10 +2,10 @@
|
|||
|
||||
There are two documents you need to read, in order:
|
||||
|
||||
* [gitolite and ssh][glssh] -- this explains how gitolite uses openssh's
|
||||
features to provide any number of virtual users over just one actual
|
||||
(unix) user, and so on
|
||||
* [Gitolite and ssh][glssh] explains how gitolite uses openssh features to
|
||||
create any number of virtual users over just one actual (unix) user, and
|
||||
distinguish between them by their public keys.
|
||||
|
||||
* [ssh troubleshooting][sts] -- this is a rather long document but as far
|
||||
as I know almost every known ssh related issue is in here. If you find
|
||||
something missing, send me an email with details.
|
||||
* [Ssh troubleshooting][sts] is a rather long document that, as far as I
|
||||
know, covers almost every known ssh related issue. If you find something
|
||||
missing, send me an email with details so I can update it.
|
||||
|
|
|
|||
|
|
@ -1,6 +0,0 @@
|
|||
# unique setups
|
||||
|
||||
This page is for unique setups that I support. At present there is only one
|
||||
-- Fedora.
|
||||
|
||||
|
||||
87
doc/files.mkd
Normal file
87
doc/files.mkd
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# files involved in gitolite
|
||||
|
||||
## install
|
||||
|
||||
Let's say you start from a totally clean slate:
|
||||
|
||||
$ pwd
|
||||
/home/gl-test
|
||||
|
||||
$ ls -a
|
||||
. .. .bash_logout .bash_profile .bashrc
|
||||
|
||||
You run `git clone -b g3 git://github.com/sitaramc/gitolite` (the '-b' option
|
||||
does the equivalent of 'git checkout g3' after the clone is done).
|
||||
|
||||
Now you have
|
||||
|
||||
$ ls -aF
|
||||
./ ../ .bash_logout .bash_profile .bashrc gitolite/
|
||||
|
||||
$ ls -aF gitolite
|
||||
./ ../ check-g2-compat* doc/ dot.pl .git/ install* src/ t/
|
||||
|
||||
If we were an existing user, we'd run the migration checker 'check-g2-compat'
|
||||
(see [here][g2migr]). For now we're only interested in "gitolite/src", so:
|
||||
|
||||
$ ls -aF gitolite/src
|
||||
./ ../ commands/ gitolite* Gitolite/ gitolite-shell* syntactic-sugar/ triggers/ VREF/
|
||||
|
||||
We check our PATH to make sure `$HOME/bin` is in it:
|
||||
|
||||
$ echo $PATH
|
||||
/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin:/home/gl-test/.local/bin:/home/gl-test/bin
|
||||
|
||||
Since it is, we run `mkdir bin; gitolite/install -ln`, and get:
|
||||
|
||||
$ mkdir bin
|
||||
$ gitolite/install -ln
|
||||
|
||||
$ ls -aF
|
||||
./ ../ .bash_logout .bash_profile .bashrc bin/ gitolite/
|
||||
|
||||
$ ls -aF bin
|
||||
./ ../ gitolite@
|
||||
|
||||
$ file bin/gitolite
|
||||
bin/gitolite: symbolic link to `/home/gl-test/gitolite/src/gitolite'
|
||||
|
||||
That's the install done. At the end of it, we have just *one* symlink in
|
||||
`$HOME/bin`; everything else is in a different directory.
|
||||
|
||||
## setup
|
||||
|
||||
Now you copy your pubkey (typically `id_rsa.pub`) from your workstation to the
|
||||
server, then run `gitolite setup -pk "yourname.pub"`. Which gives you this:
|
||||
|
||||
$ ls -aF
|
||||
./ .bash_logout .bashrc gitolite/ .gitolite.rc repositories/ .ssh/
|
||||
../ .bash_profile bin/ .gitolite/ projects.list sitaram.pub
|
||||
|
||||
$ ls -aF bin
|
||||
./ ../ gitolite@
|
||||
|
||||
$ ls -aF .gitolite
|
||||
./ ../ conf/ hooks/ keydir/ logs/
|
||||
|
||||
$ ls -aF repositories
|
||||
./ ../ gitolite-admin.git/ testing.git/
|
||||
|
||||
$ ls -aF .ssh
|
||||
./ ../ authorized_keys*
|
||||
|
||||
And that's the setup done. At the end of this step, you have
|
||||
|
||||
* `~/bin/gitolite` -- a symlink to `~/gitolite/src/gitolite`. The target of
|
||||
this symlink tells gitolite where the rest of the code is.
|
||||
* `~/gitolite/src` -- the rest of the code.
|
||||
* `~/.gitolite` -- the gitolite "admin" directory. The only thing you
|
||||
should directly touch here are the [log][] files and [hooks][]. (I.e., do
|
||||
NOT change the conf or keydir contents here; see adding [users][] and
|
||||
[repos][] for how to do that.
|
||||
* `~/.gitolite.rc` -- the [rc][] file.
|
||||
* `~/repositories` -- which contains all the repositories that gitolite will
|
||||
be managing.
|
||||
* `~/.ssh` -- which contains (at least) the `authorized_keys` file that
|
||||
provides access to users. You can look inside that file and correlate it
|
||||
with what the [ssh][] docs tell you, if you wish.
|
||||
94
doc/fm2mt.pl
Executable file
94
doc/fm2mt.pl
Executable file
|
|
@ -0,0 +1,94 @@
|
|||
#!/usr/bin/perl
|
||||
use strict;
|
||||
use warnings;
|
||||
use 5.10.0;
|
||||
|
||||
# usage: ./fm2mt.pl < g3-master-toc.mm > master-toc.mkd
|
||||
|
||||
use HTML::Entities;
|
||||
|
||||
sub out { my $out = shift; print $out; }
|
||||
|
||||
# freemind to "dense" HTML
|
||||
my @in = fm2indent();
|
||||
|
||||
out("# gitolite documentation");
|
||||
my $started = 0;
|
||||
for (@in) {
|
||||
my($indent, $text) = split ' ', $_, 2;
|
||||
$indent--;
|
||||
|
||||
if (not $indent) {
|
||||
out "\n\n## $text\n";
|
||||
$started = 0;
|
||||
next;
|
||||
}
|
||||
|
||||
if ($indent == 1) {
|
||||
# (dense mode) $text = color("red", $text);
|
||||
}
|
||||
|
||||
if ($indent <= 2) {
|
||||
# (dense mode) $text = size(2 - $indent, $text);
|
||||
} else {
|
||||
# 3 or more
|
||||
# (dense mode) $text = ("/" x ($indent-4)) . color("gray", $text);
|
||||
}
|
||||
|
||||
# normal mode
|
||||
$text = "\n" . (" " x ($indent-1)) . " * $text";
|
||||
# (dense mode) out " -- " if $started++;
|
||||
out $text;
|
||||
}
|
||||
|
||||
sub size {
|
||||
my ($s, $t) = @_;
|
||||
return "<font size=\"+" . $s . "\">$t</font>" if $s;
|
||||
return $t;
|
||||
}
|
||||
|
||||
sub color {
|
||||
my ($c, $t) = @_;
|
||||
return "<font color=\"$c\">$t</font>";
|
||||
}
|
||||
|
||||
sub get_indent {
|
||||
my $_ = shift;
|
||||
chomp;
|
||||
return () unless /\S/;
|
||||
if (/^(#+) (.*)/) {
|
||||
return (length($1)-1, $2);
|
||||
}
|
||||
if (/^( +) \* (.*)/) {
|
||||
my $t = $2;
|
||||
my $i = length($1);
|
||||
die 1 if $i % 4;
|
||||
$i = $i/4 + 3;
|
||||
|
||||
return ($i, $t);
|
||||
}
|
||||
return ();
|
||||
}
|
||||
|
||||
sub fm2indent {
|
||||
my @out = ();
|
||||
my $indent=0;
|
||||
|
||||
while (<>)
|
||||
{
|
||||
next unless /^<node / or /^<\/node/;
|
||||
if (/^<\/node>$/)
|
||||
{
|
||||
$indent--;
|
||||
next;
|
||||
}
|
||||
next unless /TEXT="([^"]*)"/;
|
||||
my $text = decode_entities($1);
|
||||
|
||||
push @out, "\n$indent $text" if $indent;
|
||||
|
||||
$indent++ unless (/\/>/);
|
||||
}
|
||||
|
||||
return @out;
|
||||
}
|
||||
|
|
@ -7,24 +7,27 @@ severity. **The ones in the first section are IMPORTANT because they allow
|
|||
access that was previously not allowed -- please fix your config before using
|
||||
the new gitolite!**
|
||||
|
||||
### fallthru in NAME rules
|
||||
### NAME rules
|
||||
|
||||
Fallthru on all VREFs is "success" now, so any NAME/ rules you have **MUST**
|
||||
change the ruleset in some way to maintain the same restrictions. The
|
||||
simplest is to add the following line to the end of each repo's rule list:
|
||||
1. NAME/ rules must be changed to VREF/NAME/
|
||||
|
||||
- NAME/ = @all
|
||||
2. Fallthru on all VREFs is "success" now, so any NAME/ rules you have
|
||||
**MUST** change the ruleset in some way to maintain the same restrictions.
|
||||
The simplest is to add the following line to the end of each repo's rule
|
||||
list:
|
||||
|
||||
- VREF/NAME/ = @all
|
||||
|
||||
### subconf command in admin repo
|
||||
|
||||
(This is also affected by the previous issue, 'fallthru in NAME rules'; please
|
||||
read that as well).
|
||||
(This is also affected by the previous issue, 'NAME rules'; please read that
|
||||
as well).
|
||||
|
||||
If you're using delegation in your admin conf setup, please add the following
|
||||
lines to the end of the gitolite-admin rules in your conf/gitolite.conf file:
|
||||
|
||||
repo gitolite-admin
|
||||
- NAME/ = @all
|
||||
- VREF/NAME/ = @all
|
||||
|
||||
subconf "fragments/*.conf"
|
||||
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ put that contain the words "see docs":
|
|||
|
||||
same as above
|
||||
|
||||
* `fallthru in NAME rules`
|
||||
* `NAME rules`
|
||||
|
||||
**This is a significant difference and affects access badly (gives access
|
||||
that would otherwise not be given)**. Please see the [list of non-RC
|
||||
|
|
|
|||
153
doc/g3-master-toc.mm
Executable file
153
doc/g3-master-toc.mm
Executable file
|
|
@ -0,0 +1,153 @@
|
|||
<map version="0.9.0">
|
||||
<!-- To view this file, download free mind mapping software FreeMind from http://freemind.sourceforge.net -->
|
||||
<node CREATED="1331107648858" ID="ID_187992057" MODIFIED="1333299050498" TEXT="g3-master-index">
|
||||
<node CREATED="1333299038338" ID="ID_1574733847" MODIFIED="1333536460445" POSITION="right" TEXT="[Introduction][index]">
|
||||
<node CREATED="1333466035663" ID="ID_974293172" MODIFIED="1333536536267" TEXT="(for [current][g2] gitolite (v2) users)"/>
|
||||
<node CREATED="1333466047943" ID="ID_1283272433" MODIFIED="1333536530576" TEXT="[quick links][ql]"/>
|
||||
<node CREATED="1333326589821" ID="ID_195282410" MODIFIED="1333340829999" TEXT="[what][] is gitolite"/>
|
||||
<node CREATED="1333326593927" ID="ID_1110367572" MODIFIED="1333340841907" TEXT="[why][] might you need it"/>
|
||||
<node CREATED="1333536552704" ID="ID_1607033994" MODIFIED="1333536835577" TEXT="[contact][] info, mailing list, IRC channel"/>
|
||||
<node CREATED="1333536577819" ID="ID_1858469252" MODIFIED="1333536835576" TEXT="[license][] info"/>
|
||||
</node>
|
||||
<node CREATED="1333300010980" ID="ID_1728019284" MODIFIED="1333616327427" POSITION="right" TEXT="help for [emergencies][]">
|
||||
<node CREATED="1333300016176" ID="ID_30257493" MODIFIED="1333453799784" TEXT="[lost][lost-key] admin key/access"/>
|
||||
<node CREATED="1333327185236" ID="ID_910862972" MODIFIED="1333471145297" TEXT="[bypass][]ing gitolite"/>
|
||||
<node CREATED="1333328183948" ID="ID_564351456" MODIFIED="1333453834497" TEXT="[clean][]ing out a botched install"/>
|
||||
<node CREATED="1333326808789" ID="ID_54380370" MODIFIED="1333631901528" TEXT="[common][ce] errors (TBD)"/>
|
||||
<node CREATED="1333597279461" ID="ID_547537696" MODIFIED="1333631907824" TEXT="[uncommon][ue] errors"/>
|
||||
<node CREATED="1333328539885" ID="ID_162892604" MODIFIED="1333527642132" TEXT="things that are [not gitolite problems][ngp]"/>
|
||||
</node>
|
||||
<node CREATED="1333466070125" ID="ID_1329733023" MODIFIED="1333527838066" POSITION="right" TEXT="[WARNINGS][]"/>
|
||||
<node CREATED="1333326560775" ID="ID_1030406941" MODIFIED="1333631954561" POSITION="right" TEXT="[quick][qi] install, setup, and clone"/>
|
||||
<node CREATED="1333465293309" ID="ID_1405252383" MODIFIED="1333526188455" POSITION="right" TEXT="[install][]">
|
||||
<node CREATED="1333327826145" ID="ID_519306224" MODIFIED="1333467083667" TEXT="notes and naming conventions"/>
|
||||
<node CREATED="1333328069297" ID="ID_624460163" MODIFIED="1333465312762" TEXT="requirements">
|
||||
<node CREATED="1333328127550" ID="ID_368487912" MODIFIED="1333537067223" TEXT="your skills"/>
|
||||
<node CREATED="1333328123855" ID="ID_1146334636" MODIFIED="1333339551947" TEXT="server"/>
|
||||
<node CREATED="1333328126057" ID="ID_899541385" MODIFIED="1333328127275" TEXT="client"/>
|
||||
</node>
|
||||
<node CREATED="1333328151051" ID="ID_1577506173" MODIFIED="1333465323159" TEXT="getting the software"/>
|
||||
<node CREATED="1333328156575" ID="ID_208746322" MODIFIED="1333465333727" TEXT="the actual install"/>
|
||||
<node CREATED="1333467553366" ID="ID_926614739" MODIFIED="1333467556140" TEXT="upgrading"/>
|
||||
<node CREATED="1333328592876" ID="ID_237795046" MODIFIED="1333466108368" TEXT="packaging gitolite"/>
|
||||
<node CREATED="1333327776230" ID="ID_1431739921" MODIFIED="1333467569937" TEXT="migrating"/>
|
||||
</node>
|
||||
<node CREATED="1333301194129" ID="ID_746196740" MODIFIED="1333471816303" POSITION="right" TEXT="[setup][]"/>
|
||||
<node CREATED="1333299674481" ID="ID_714407264" MODIFIED="1333528325006" POSITION="right" TEXT="gitolite [admin][]istration">
|
||||
<node CREATED="1333299694885" ID="ID_1916098884" MODIFIED="1333537908466" TEXT="[server][]-side">
|
||||
<node CREATED="1333327917312" ID="ID_1266878047" MODIFIED="1333537539764" TEXT="([link][WARNINGS]: important cautions on server side activity)"/>
|
||||
<node CREATED="1333301196071" ID="ID_760433725" MODIFIED="1333537537075" TEXT="changing settings in the [rc][] file"/>
|
||||
<node CREATED="1333537546089" ID="ID_2500021" MODIFIED="1333537553267" TEXT="installing custom [hooks][]"/>
|
||||
<node CREATED="1333537563152" ID="ID_472486055" MODIFIED="1333537616205" TEXT="([link][existing]: moving existing repos into gitolite)"/>
|
||||
</node>
|
||||
<node CREATED="1333299702754" ID="ID_609351656" MODIFIED="1333537921248" TEXT="[access control][conf] (the gitolite.conf file)">
|
||||
<node CREATED="1333566502470" ID="ID_1931486515" MODIFIED="1333583575642" TEXT="[example][confex] of a conf file"/>
|
||||
<node CREATED="1333300715360" ID="ID_41940351" MODIFIED="1333547591053" TEXT="basic [syntax][]">
|
||||
<node CREATED="1333300732151" ID="ID_1494555007" MODIFIED="1333300733944" TEXT="include files"/>
|
||||
<node CREATED="1333300741424" ID="ID_416012685" MODIFIED="1333513004487" TEXT="([link][sugar]: syntactic sugar)"/>
|
||||
</node>
|
||||
<node CREATED="1333300461624" ID="ID_1848362678" MODIFIED="1333529103568" TEXT="[groups][] (of users and repos)">
|
||||
<node CREATED="1333300884900" ID="ID_1412135290" MODIFIED="1333300893755" TEXT="special: '@all'"/>
|
||||
<node CREATED="1333300437860" ID="ID_897670108" MODIFIED="1333300770020" TEXT="(link: storing user group info in LDAP)"/>
|
||||
</node>
|
||||
<node CREATED="1333299715546" ID="ID_1916374076" MODIFIED="1333529107922" TEXT="adding and removing [users][]">
|
||||
<node CREATED="1333326840977" ID="ID_1723439755" MODIFIED="1333517370375" TEXT="multiple keys per user"/>
|
||||
</node>
|
||||
<node CREATED="1333299719741" ID="ID_275665792" MODIFIED="1333529112764" TEXT="adding and removing [repos][]">
|
||||
<node CREATED="1333327426500" ID="ID_1964948889" MODIFIED="1333518450199" TEXT="renaming repos"/>
|
||||
</node>
|
||||
<node CREATED="1333300309235" ID="ID_1437714859" MODIFIED="1333529121211" TEXT="defining access [rules][]">
|
||||
<node CREATED="1333584760127" ID="ID_469376519" MODIFIED="1333584767343" TEXT="what does a rule look like?"/>
|
||||
<node CREATED="1333326976405" ID="ID_563906836" MODIFIED="1333584770230" TEXT="when are the rules checked?"/>
|
||||
<node CREATED="1333535584526" ID="ID_957313656" MODIFIED="1333584774497" TEXT="how are the rules matched?"/>
|
||||
<node CREATED="1333301045521" ID="ID_1228046254" MODIFIED="1333536127886" TEXT="summary of [permissions][perms]"/>
|
||||
<node CREATED="1333599586661" ID="ID_1785519868" MODIFIED="1333599590134" TEXT="additional topics">
|
||||
<node CREATED="1333599591055" ID="ID_1379421123" MODIFIED="1333599606966" TEXT="[rule accumulation][rule-accum]"/>
|
||||
<node CREATED="1333599613910" ID="ID_1760840175" MODIFIED="1333599634987" TEXT="applying [deny rules][deny-rules] during the pre-git check"/>
|
||||
</node>
|
||||
<node CREATED="1333535705100" ID="ID_1768473150" MODIFIED="1333535718347" TEXT="([link][refex]: refexes)"/>
|
||||
<node CREATED="1333535719180" ID="ID_431454064" MODIFIED="1333626093118" TEXT="([link][write-types]: different types of write operations)"/>
|
||||
<node CREATED="1333300541352" ID="ID_1407372791" MODIFIED="1333536011832" TEXT="([link][vref]: virtual refs)"/>
|
||||
</node>
|
||||
<node CREATED="1333521966550" ID="ID_462181887" MODIFIED="1333529126015" TEXT="gitolite [options][]"/>
|
||||
<node CREATED="1333521972558" ID="ID_1180232837" MODIFIED="1333536152124" TEXT=""[git config][git-config]" keys and values"/>
|
||||
<node CREATED="1333299726939" ID="ID_1229702100" MODIFIED="1333601090414" TEXT="["wild"][wild] repos (user created repos)">
|
||||
<node CREATED="1333329088398" ID="ID_533855844" MODIFIED="1333630553509" TEXT="quick introduction"/>
|
||||
<node CREATED="1333599529910" ID="ID_1393418948" MODIFIED="1333630403135" TEXT="(admin) declaring wild repos in the conf file"/>
|
||||
<node CREATED="1333629999807" ID="ID_139250181" MODIFIED="1333630432141" TEXT="(user) [creating][create] a specific repo"/>
|
||||
<node CREATED="1333599928516" ID="ID_439610891" MODIFIED="1333600901677" TEXT="repo patterns"/>
|
||||
<node CREATED="1333329137043" ID="ID_1876270574" MODIFIED="1333599539626" TEXT="roles"/>
|
||||
<node CREATED="1333329119800" ID="ID_1196899132" MODIFIED="1333600898568" TEXT="adding other roles">
|
||||
<node CREATED="1333630582435" ID="ID_792555451" MODIFIED="1333630596161" TEXT="[IMPORTANT WARNING ABOUT THIS FEATURE][rolenamewarn]"/>
|
||||
</node>
|
||||
<node CREATED="1333299760157" ID="ID_1787203633" MODIFIED="1333600934866" TEXT="listing wild repos"/>
|
||||
<node CREATED="1333299751513" ID="ID_1503072743" MODIFIED="1333600958915" TEXT="deleting wild repos"/>
|
||||
</node>
|
||||
</node>
|
||||
</node>
|
||||
<node CREATED="1333326619348" ID="ID_697668065" MODIFIED="1333537363837" POSITION="right" TEXT="what your [user][]s need to know"/>
|
||||
<node CREATED="1333300236173" ID="ID_1026631043" MODIFIED="1333607025161" POSITION="right" TEXT="[special][] features/setups">
|
||||
<node CREATED="1333327232490" ID="ID_849345095" MODIFIED="1333631333199" TEXT="[disabling pushes][writable] to take backups"/>
|
||||
<node CREATED="1333300243659" ID="ID_106425369" MODIFIED="1333604404937" TEXT="[personal][pers] branches"/>
|
||||
<node CREATED="1333300501314" ID="ID_1819387758" MODIFIED="1333606161557" TEXT="[delegating][deleg] access control responsibilities">
|
||||
<node CREATED="1333606177736" ID="ID_1153299625" MODIFIED="1333606191734" TEXT="([link][NAME]: the NAME VREF)"/>
|
||||
<node CREATED="1333300531135" ID="ID_206710372" MODIFIED="1333606536438" TEXT="the [subconf][] command"/>
|
||||
</node>
|
||||
<node CREATED="1333300925828" ID="ID_1848845001" MODIFIED="1333626115598" TEXT="([link][partial-copy]: faking selective READ control)"/>
|
||||
</node>
|
||||
<node CREATED="1333327469941" ID="ID_1230549116" MODIFIED="1333607053576" POSITION="right" TEXT="interfacing with [external][] tools">
|
||||
<node CREATED="1333327476469" ID="ID_1887257091" MODIFIED="1333327480072" TEXT="gitweb">
|
||||
<node CREATED="1333504877358" ID="ID_1448276401" MODIFIED="1333625357439" TEXT="changing the [UMASK][umask]"/>
|
||||
</node>
|
||||
<node CREATED="1333327480559" ID="ID_513431483" MODIFIED="1333327483014" TEXT="git-daemon"/>
|
||||
</node>
|
||||
<node CREATED="1333326753755" ID="ID_16865998" MODIFIED="1333625410973" POSITION="right" TEXT="[mirroring][]"/>
|
||||
<node CREATED="1333299976094" ID="ID_1948442779" MODIFIED="1333625437290" POSITION="right" TEXT="[rare][]/one-time activities">
|
||||
<node CREATED="1333299985915" ID="ID_530631392" MODIFIED="1333471109149" TEXT="moving [existing][] repos into gitolite"/>
|
||||
<node CREATED="1333300099453" ID="ID_1521618753" MODIFIED="1333625463686" TEXT="[moving][] servers"/>
|
||||
</node>
|
||||
<node CREATED="1333299141061" ID="ID_37630832" MODIFIED="1333625569805" POSITION="right" TEXT="[customisation][cust]">
|
||||
<node CREATED="1333299458493" ID="ID_992003929" MODIFIED="1333625583059" TEXT="types of non-core programs">
|
||||
<node CREATED="1333625624553" ID="ID_1205434644" MODIFIED="1333639834277" TEXT="([link][non-core]: non-core programs shipped with gitolite)"/>
|
||||
</node>
|
||||
<node CREATED="1333625674563" ID="ID_603892527" MODIFIED="1333625679247" TEXT="[commands][]"/>
|
||||
<node CREATED="1333625679584" ID="ID_230664255" MODIFIED="1333625682401" TEXT="[hooks][]"/>
|
||||
<node CREATED="1333625689987" ID="ID_112339937" MODIFIED="1333625696128" TEXT="syntactic [sugar][]"/>
|
||||
<node CREATED="1333625703698" ID="ID_1165978069" MODIFIED="1333625715099" TEXT="([link][triggers]: triggers)"/>
|
||||
<node CREATED="1333625717605" ID="ID_1483309372" MODIFIED="1333625734532" TEXT="([link][vref]: VREFs)"/>
|
||||
<node CREATED="1333625757836" ID="ID_1102952567" MODIFIED="1333625766871" TEXT="[developer notes][dev-notes]">
|
||||
<node CREATED="1333625797339" ID="ID_1760918724" MODIFIED="1333625812051" TEXT="environment variables and other inputs"/>
|
||||
<node CREATED="1333625816655" ID="ID_420128580" MODIFIED="1333625818681" TEXT="APIs">
|
||||
<node CREATED="1333625820871" ID="ID_672321981" MODIFIED="1333625823262" TEXT="the shell API"/>
|
||||
<node CREATED="1333625823632" ID="ID_206993094" MODIFIED="1333625825547" TEXT="the perl API"/>
|
||||
</node>
|
||||
<node CREATED="1333625864473" ID="ID_1009525945" MODIFIED="1333625888705" TEXT="writing your own...">
|
||||
<node CREATED="1333625889803" ID="ID_323248071" MODIFIED="1333625890797" TEXT="hooks"/>
|
||||
<node CREATED="1333625891081" ID="ID_774724756" MODIFIED="1333625895322" TEXT="commands"/>
|
||||
<node CREATED="1333625956866" ID="ID_1107908272" MODIFIED="1333625960910" TEXT="trigger programs"/>
|
||||
<node CREATED="1333625961452" ID="ID_159826002" MODIFIED="1333625967173" TEXT="sugar"/>
|
||||
</node>
|
||||
</node>
|
||||
</node>
|
||||
<node CREATED="1333300577608" ID="ID_583410113" MODIFIED="1333537235253" POSITION="right" TEXT="background info">
|
||||
<node CREATED="1333299088617" ID="ID_1919571562" MODIFIED="1333537208005" TEXT="[files and directories][files] involved in install+setup"/>
|
||||
<node CREATED="1333300378018" ID="ID_584192327" MODIFIED="1333536676126" TEXT="[auth][]entication versus authorisation">
|
||||
<node CREATED="1333300390847" ID="ID_384452374" MODIFIED="1333453722001" TEXT="interfacing with [other authentication][otherauth] systems"/>
|
||||
<node CREATED="1333300437860" ID="ID_99922512" MODIFIED="1333453750215" TEXT="getting user group info from [LDAP][ldap]"/>
|
||||
</node>
|
||||
<node CREATED="1333301124871" ID="ID_931083276" MODIFIED="1333453771459" TEXT="[ssh][]"/>
|
||||
<node CREATED="1333301127955" ID="ID_1527577153" MODIFIED="1333453780482" TEXT="[regular expressions][regex]"/>
|
||||
</node>
|
||||
<node CREATED="1333300587911" ID="ID_91544543" MODIFIED="1333641141649" POSITION="right" TEXT="contributed software, tools, and documentation">
|
||||
<node CREATED="1333300608550" ID="ID_1486318266" MODIFIED="1333626152668" TEXT="TBD"/>
|
||||
</node>
|
||||
<node CREATED="1333301296248" ID="ID_571518549" MODIFIED="1333526198202" POSITION="right" TEXT="TBD">
|
||||
<node CREATED="1333327082853" ID="ID_488765250" MODIFIED="1333327089444" TEXT="log file format, LOG_EXTRA"/>
|
||||
<node CREATED="1333301298504" ID="ID_60946303" MODIFIED="1333301300418" TEXT="smart http"/>
|
||||
<node CREATED="1333301308136" ID="ID_1900285587" MODIFIED="1333301311863" TEXT="hub"/>
|
||||
<node CREATED="1333301312124" ID="ID_843247306" MODIFIED="1333301313052" TEXT="sskm"/>
|
||||
<node CREATED="1333328274461" ID="ID_248606591" MODIFIED="1333328277083" TEXT="mob branches"/>
|
||||
<node CREATED="1333328277387" ID="ID_1027016949" MODIFIED="1333328280083" TEXT="password access"/>
|
||||
</node>
|
||||
</node>
|
||||
</map>
|
||||
66
doc/git-config.mkd
Normal file
66
doc/git-config.mkd
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# "git-config" keys and values
|
||||
|
||||
Here's all you want to know about setting repo-specific git-config values.
|
||||
|
||||
(Original version thanks to teemu dot matilainen at iki dot fi)
|
||||
|
||||
> ----
|
||||
|
||||
> **Note**: this won't work unless the rc file has the right settings;
|
||||
> please see `$GIT_CONFIG_KEYS` in the [rc file doc][rc].
|
||||
|
||||
> ----
|
||||
|
||||
The syntax is simple:
|
||||
|
||||
config sectionname.keyname = [optional value_string]
|
||||
|
||||
For example:
|
||||
|
||||
repo gitolite
|
||||
config hooks.mailinglist = gitolite-commits@example.tld
|
||||
config hooks.emailprefix = "[gitolite] "
|
||||
config foo.bar = ""
|
||||
config foo.baz =
|
||||
|
||||
This does either a plain "git config section.key value" (for the first 3
|
||||
examples above) or "git config --unset-all section.key" (for the last
|
||||
example). Other forms of the `git config` command (`--add`, the
|
||||
`value_regex`, etc) are not supported.
|
||||
|
||||
> ----
|
||||
|
||||
> **WARNING**: simply deleting the config line from the `conf/gitolite.conf`
|
||||
> file will *not* delete the variable from `repo.git/config`. The syntax in
|
||||
> the last example is the *only* way to make gitolite execute a
|
||||
> `--unset-all` operation on the given key.
|
||||
|
||||
> ----
|
||||
|
||||
You can also use the special value `%GL_REPO` in the string to save typing:
|
||||
|
||||
repo foo bar baz
|
||||
config hooks.mailinglist = %GL_REPO-commits@example.tld
|
||||
config hooks.emailprefix = "[%GL_REPO] "
|
||||
|
||||
You can repeat the 'config' line as many times as you like, and the last
|
||||
occurrence will be the one in effect. This allows you to override settings
|
||||
just for one project, as in this example:
|
||||
|
||||
repo @all
|
||||
config hooks.mailinglist = %GL_REPO-commits@example.tld
|
||||
config hooks.emailprefix = "[%GL_REPO] "
|
||||
|
||||
repo customer-project
|
||||
# different mailing list
|
||||
config hooks.mailinglist = announce@customer.tld
|
||||
|
||||
The "delete config variable" syntax can also be used, if you wish:
|
||||
|
||||
repo secret # no emails for this one please
|
||||
config hooks.mailinglist =
|
||||
config hooks.emailprefix =
|
||||
|
||||
As you can see, the general idea is to place the most generic ones (`repo
|
||||
@all`, or repo patterns like `repo foo.*`) first, and place more specific ones
|
||||
later to override the generic settings.
|
||||
|
|
@ -1,6 +1,4 @@
|
|||
# parts of the conf file
|
||||
|
||||
## #group group definitions
|
||||
# group definitions
|
||||
|
||||
You can group repos or users for convenience. The syntax is the same for both
|
||||
and does not distinguish; until you *use* the group name it could really be
|
||||
|
|
@ -26,7 +24,7 @@ right there (meaning later additions will not appear in the second group).
|
|||
|
||||
# wally is NOT part of @staff
|
||||
|
||||
### special group `@all`
|
||||
## special group `@all`
|
||||
|
||||
`@all` is a special group name that is often convenient to use if you really
|
||||
mean "all repos" or "all users".
|
||||
|
|
@ -5,49 +5,47 @@ fine-grained access control and many more powerful features.
|
|||
|
||||
Here's more on [what][] it is and [why][] you might need it.
|
||||
|
||||
<font color="gray">
|
||||
|
||||
## #g2 (for current gitolite (v2) users)
|
||||
|
||||
For current gitolite (call it "g2" for convenience) users,
|
||||
|
||||
* [Why][g3why] I rewrote gitolite.
|
||||
* Development [status][dev-status] (**should change often for a while**)
|
||||
* Development [status][dev-status].
|
||||
* Specific migration [issues and steps][g2migr].
|
||||
|
||||
Quick links:
|
||||
</font>
|
||||
|
||||
* [Minimum requirements][minreq].
|
||||
* Here's how to [get started][qi] installing and setting it up
|
||||
## #ql quick links
|
||||
|
||||
* Minimum [requirements][req].
|
||||
* Here's how to do a [quick install, setup, and clone][qi].
|
||||
* Don't know ssh well enough? [Learn][ssh]. It's **IMPORTANT**.
|
||||
* [Add users and repos][add].
|
||||
* Learn about fine-grained access control with the [conf][] file
|
||||
* Explain gitolite to your [users][].
|
||||
* Add [users][] and [repos][].
|
||||
* Learn about fine-grained access control with the [conf][] file.
|
||||
* Explain gitolite to your [users][user].
|
||||
|
||||
Not so "quick" links:
|
||||
|
||||
* The "master table of contents" link at the top of each page is the
|
||||
**first** place you should check when looking for anything.
|
||||
|
||||
* Want to do more than just add users and repos and control their access?
|
||||
Here's how to [customise][cust] your server installation.
|
||||
|
||||
Additional reading for Unix newbies:
|
||||
|
||||
* [Regular Expressions][regex]
|
||||
The rest of the documentation is in the "master index" link at the top of each
|
||||
page on this website. This is the first place you should search when looking
|
||||
for specific information.
|
||||
|
||||
## #what What is gitolite?
|
||||
|
||||
Gitolite is an access control layer on top of git. Here are the features that
|
||||
most people see:
|
||||
|
||||
* use a single unix user ("real" user) on the server
|
||||
* provide access to many gitolite users
|
||||
* Use a single unix user ("real" user) on the server.
|
||||
* Provide access to many gitolite users:
|
||||
* they are not "real" users
|
||||
* they do not get shell access
|
||||
* control access to many git repositories
|
||||
* Control access to many git repositories:
|
||||
* read access controlled at the repo level
|
||||
* write access controlled at the branch/tag/file/directory level,
|
||||
including who can rewind, create, and delete branches/tags
|
||||
* can be installed without root access, assuming git and perl are already
|
||||
installed
|
||||
* authentication is most commonly done using sshd, but you can also use
|
||||
* Can be installed without root access, assuming git and perl are already
|
||||
installed.
|
||||
* Authentication is most commonly done using sshd, but you can also use
|
||||
httpd if you prefer (this may require root access).
|
||||
|
||||
## #contact contact
|
||||
|
|
|
|||
168
doc/install.mkd
168
doc/install.mkd
|
|
@ -1,37 +1,122 @@
|
|||
# different ways to install gitolite
|
||||
|
||||
Gitolite has only one server side "command" now, much like git itself. And
|
||||
it's been designed so that you don't even really have to *install* it, as you
|
||||
will see.
|
||||
# installing gitolite
|
||||
|
||||
**NOTE**: if you're migrating from g2, there are some settings that MUST be
|
||||
dealt with **before** running `gitolite setup`; please read the [g2
|
||||
migration][g2migr] page and linked pages, and especially the one on
|
||||
'presetting the rc file][rc-preset].
|
||||
[presetting the rc file][rc-preset].
|
||||
|
||||
## simplest
|
||||
## notes and naming conventions
|
||||
|
||||
1. Put all of `src` in one place, doesn't matter where; let's call it
|
||||
/foo/bar.
|
||||
Gitolite uses a single "real" (i.e., unix) user to provide secure access to
|
||||
git repos to any number of "virtual" users, without giving them a shell.
|
||||
|
||||
2. Use the full path to run any gitolite commands, for example:
|
||||
The real user used is called the **hosting user**. Typically this user is
|
||||
*git*, and that is what we will use throughout the documentation. However
|
||||
RPMs and DEBs create a user called *gitolite* for this, so adjust instructions
|
||||
and examples accordingly.
|
||||
|
||||
/foo/bar/gitolite setup -pk sitaram.pub
|
||||
Notes:
|
||||
|
||||
## almost as simple
|
||||
* Any unix user can be a hosting user.
|
||||
* Which also means you can have several hosting users on the same machine.
|
||||
* The URLs used will be of the form `git@host:reponame` (or its longer
|
||||
equivalent starting with `ssh://`). The `.git` at the end is optional. I
|
||||
recommend you leave it out, so your reponames are consistent with what the
|
||||
conf file uses.
|
||||
|
||||
1. (same as above)
|
||||
## #req requirements
|
||||
|
||||
2. Symlink /foo/bar/gitolite to some directory that is on your PATH. For
|
||||
example:
|
||||
### your skills
|
||||
|
||||
ln -sf /foo/bar/gitolite ~/bin
|
||||
* If you're installing gitolite, you're a "system admin", like it or not.
|
||||
Ssh is therefore a necessary skill. Please take the time to learn at
|
||||
least enough to get passwordless access working.
|
||||
|
||||
Now you can just say
|
||||
* You also need to be somewhat familiar with git itself. You cannot
|
||||
administer a whole bunch of git repositories if you don't know the basics
|
||||
of git.
|
||||
|
||||
gitolite setup -pk sitaram.pub
|
||||
* Some familiarity with Unix and shells is probably required.
|
||||
|
||||
## packagers
|
||||
* Regular expressions are a big part of gitolite in many places but
|
||||
familiarity is not necessary to do *basic* access control.
|
||||
|
||||
### server
|
||||
|
||||
* any Unix system with a posix compatible "sh".
|
||||
* git version 1.6.6 or later
|
||||
* perl 5.8.8 or later
|
||||
* openssh (almost any version). Optional if you're using the http backend
|
||||
(which is still a TODO item!)
|
||||
* a dedicated Unix userid to be the hosting user, usually "git" but it can
|
||||
be any user, even your own normal one. (If you're using an RPM/DEB the
|
||||
install probably created one called "gitolite").
|
||||
|
||||
Also see the [WARNINGS][] page for more on what gitolite expects on the server
|
||||
side.
|
||||
|
||||
### client
|
||||
|
||||
* openssh client
|
||||
* git 1.6.6 or later. Almost any git client will work, as long as it knows
|
||||
how to use ssh keys and send the right one along.
|
||||
|
||||
## getting the software
|
||||
|
||||
git clone -b g3 git://github.com/sitaramc/gitolite
|
||||
|
||||
The -b g3' is needed until g3 becomes "master". Current estimates put this
|
||||
around June 2012, when the old gitolite (upto v2.x) will be retired and
|
||||
supported only for security issues.
|
||||
|
||||
## the actual install
|
||||
|
||||
Gitolite has only one server side "command" now, much like git itself. This
|
||||
command is `gitolite`. You don't need to place it anywhere special; worst
|
||||
case you run it with the full path.
|
||||
|
||||
"Installation" consists of the following options:
|
||||
|
||||
1. Keep the sources anywhere and use the full path to run the `gitolite`
|
||||
command.
|
||||
2. Keep the sources anywhere and symlink *just* the `gitolite` program to
|
||||
some directory on your `$PATH`.
|
||||
3. Copy the sources somewhere and use that path to run the `gitolite`
|
||||
command.
|
||||
|
||||
Option 2 is the best for general use.
|
||||
|
||||
There is a program called 'install' that helps you do these easily. Assuming
|
||||
your cloned the repo like this:
|
||||
|
||||
git clone -b g3 git://github.com/sitaramc/gitolite
|
||||
|
||||
you can run the 'install' command in 3 different ways:
|
||||
|
||||
# option 1
|
||||
gitolite/install
|
||||
|
||||
# option 2
|
||||
gitolite/install -ln
|
||||
# defaults to $HOME/bin, or use a specific directory:
|
||||
gitolite/install -ln /usr/local/bin
|
||||
|
||||
# option 3
|
||||
gitolite/install -to /usr/local/gitolite/bin
|
||||
|
||||
Creating a symlink doesn't need a separate program but 'install' also runs
|
||||
`git describe` to create a VERSION file, which, trust me, is important!
|
||||
|
||||
**Next step**: run [**setup**][setup].
|
||||
|
||||
## upgrading
|
||||
|
||||
Just put the new version on top of wherever you kept the old one. That's it.
|
||||
|
||||
If you feel it should require a little more effort, pretend I said "you have
|
||||
to then run `gitolite setup`". Won't hurt...
|
||||
|
||||
## packaging gitolite
|
||||
|
||||
1. Put src/Gitolite in `/usr/share/perl5/vendor_perl` or some such place.
|
||||
|
||||
|
|
@ -39,25 +124,44 @@ migration][g2migr] page and linked pages, and especially the one on
|
|||
git's 150 executables in /usr/libexec/git-core, so maybe
|
||||
/usr/libexec/gitolite?)
|
||||
|
||||
3. Symlink 'gitolite' to /usr/bin or something, similar to step 2 above,
|
||||
3. Symlink 'gitolite' to /usr/bin or something, similar to option 2.
|
||||
|
||||
OR
|
||||
|
||||
Put it directly in /usr/bin, and hardcode `GL_BINDIR` into it to tell it
|
||||
where the others are. I'd prefer it if you did not do this but you can.
|
||||
|
||||
----
|
||||
|
||||
Bottom line:
|
||||
**Bottom line**:
|
||||
|
||||
* `GL_BINDIR` must point to a place that contains `commands`, `VREF`, and
|
||||
`syntactic-sugar` (so they must all be sibling directories).
|
||||
* The `Gitolite` directory can also be there, or it can be anywhere in
|
||||
perl's `@INC` path.
|
||||
|
||||
## upgrading
|
||||
## migrating
|
||||
|
||||
Just put the new version on top of wherever you kept the old one. That's it.
|
||||
There are a lot of migration hints and notes; see links at the top of this
|
||||
document.
|
||||
|
||||
If you feel it should require a little more effort, pretend I said "you have
|
||||
to then run `gitolite setup`". Can't hurt...
|
||||
But here's the **bottom line** on migrating:
|
||||
|
||||
Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
|
||||
any repository except the gitolite-admin repo. The only thing it will
|
||||
normally touch is the `update` hook. So one fool-proof way of "migrating"
|
||||
from any older gitolite is this:
|
||||
|
||||
1. Wipe out the old gitolite, but **carefully**
|
||||
|
||||
* clone `~/repositories/gitolite-admin.git` to someplace, then delete it
|
||||
(and only it, none of the other repos!) from `~/repositories`
|
||||
* rename `~/.gitolite.rc` to something else
|
||||
* move the ~/.gitolite/logs` directory somewhere else, then delete `~/.gitolite`
|
||||
|
||||
2. Install gitolite g3; see [quick install and setup][qi] or [install][]
|
||||
followed by [setup][].
|
||||
|
||||
3. Make sure your gitolite-admin clone has the correct pubkey for the
|
||||
administrator in its `keydir` directory, then `git push -f` to the server
|
||||
to overwrite the "default" admin repo created by the install.
|
||||
|
||||
4. Handle any errors, look for migration issues, etc., as described in the
|
||||
links at the top of this page.
|
||||
|
||||
This also includes building up your new `~/.gitolite.rc` file.
|
||||
|
||||
You're done.
|
||||
|
|
|
|||
45
doc/list
45
doc/list
|
|
@ -1,45 +0,0 @@
|
|||
|
||||
index.mkd
|
||||
why.mkd
|
||||
|
||||
g3why.mkd
|
||||
dev-status.mkd
|
||||
g2migr.mkd
|
||||
g2rcdiff.mkd
|
||||
g2incompat.mkd
|
||||
g2dropped.mkd
|
||||
g2alt.mkd
|
||||
|
||||
minreq.mkd
|
||||
qi.mkd
|
||||
install.mkd
|
||||
add.mkd
|
||||
users.mkd
|
||||
|
||||
conf.mkd
|
||||
|
||||
group.mkd
|
||||
repo.mkd
|
||||
rules.mkd
|
||||
refex.mkd
|
||||
write-types.mkd
|
||||
|
||||
rc.mkd
|
||||
|
||||
cust.mkd
|
||||
triggers.mkd
|
||||
vref.mkd
|
||||
|
||||
non-core.mkd
|
||||
|
||||
dev-notes.mkd
|
||||
|
||||
misc.mkd
|
||||
pw.mkd
|
||||
testing.mkd
|
||||
extras/auth.mkd
|
||||
extras/nagp.mkd
|
||||
extras/regex.mkd
|
||||
extras/ssh.mkd
|
||||
extras/gitolite-and-ssh.mkd
|
||||
extras/ssh-troubleshooting.mkd
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# minimum requirements for gitolite
|
||||
|
||||
**Client**:
|
||||
|
||||
* git 1.6.6 or greater
|
||||
* an ssh client that can talk to an openssh server, and can generate keys in
|
||||
openssh's default format (the pubkey is just one long line). Gitolite
|
||||
will [not currently][pw1] convert such keys.
|
||||
|
||||
For people still using Windows, msysgit works fine. If you're using
|
||||
[putty/plink][ens], God bless you. (It'll work, but I still want him to bless
|
||||
you).
|
||||
|
||||
TODO: when smart http support works, ssh will no longer be a *requirement*,
|
||||
merely a *strong* suggestion :-)
|
||||
|
||||
**Server**
|
||||
|
||||
* git 1.6.6 or greater
|
||||
* perl 5.8.8 or greater
|
||||
* an ssh server compatible with openssh, especially it's authorized keys
|
||||
file format and features.
|
||||
* any Unix or Unix like OS. That said, I've occasionally had some weird
|
||||
reports from [Mac OSX servers][ens]; good luck.
|
||||
* a single, dedicated, userid to host it (usually 'git' or 'gitolite').
|
||||
|
||||
These version numbers are subject to fine-tuning as I get feedback and make
|
||||
fixes where possible and needed.
|
||||
|
||||
Sshd must be configured so that each users authkeys file is in the user's
|
||||
`$HOME`, inside `.ssh/authorized_keys`, and not in some central
|
||||
/var/something.
|
||||
|
|
@ -1,18 +1,19 @@
|
|||
# mirroring using gitolite
|
||||
|
||||
**WARNING** existing gitolite mirroring users please note: significant changes
|
||||
in syntax and usage compared to g2. The most important change is that `config
|
||||
gitolite.mirror.master` changes to `option mirror.master`, and similarly for
|
||||
'slaves' and redirectOK. In addition, the special value for 'redirectOK'
|
||||
changes from '1' to 'all'. The second big change is the disappearance of the
|
||||
ambiguously named 'keys' (for example `gitolite.mirror.hourly` etc., in the
|
||||
old mirroring doc) -- all that complexity is yours to handle now :-)
|
||||
**WARNING** existing gitolite mirroring users please note: **there are
|
||||
significant changes** in syntax and usage compared to g2. The most important
|
||||
change is that `config gitolite.mirror.master` changes to `option
|
||||
mirror.master`, and similarly for 'slaves' and redirectOK. In addition, the
|
||||
special value for 'redirectOK' changes from '1' to 'all'. The second big
|
||||
change is the disappearance of the ambiguously named 'keys' (for example
|
||||
`gitolite.mirror.hourly` etc., in the old mirroring doc) -- all that
|
||||
complexity is yours to handle now :-)
|
||||
|
||||
----
|
||||
|
||||
Mirroring is simple: you have one "master" and one or more "slaves". The
|
||||
slaves get updates only from the master; to the rest of the world they are at
|
||||
best read-only.
|
||||
Mirroring is simple: you have one "master" server and one or more "slave"
|
||||
servers. The slaves get updates only from the master; to the rest of the
|
||||
world they are at best read-only.
|
||||
|
||||
Gitolite extends this simple notion in the following ways:
|
||||
|
||||
|
|
@ -52,12 +53,12 @@ file settings and syntax.
|
|||
|
||||
### the initial setup and the rc file
|
||||
|
||||
On each server:
|
||||
On **each** server:
|
||||
|
||||
* install gitolite normally. Make clones of each server's 'gitolite-admin'
|
||||
* install gitolite normally. Make clones of the server's 'gitolite-admin'
|
||||
repo on your workstation so you can admin them all from one place.
|
||||
|
||||
* give each server a short, simple, "hostname" and set the HOSTNAME in the
|
||||
* give the server a short, simple, "hostname" and set the HOSTNAME in the
|
||||
rc file to this name, for example 'mars'.
|
||||
|
||||
* run ssh-keygen if needed and get an ssh key pair for the server. Copy the
|
||||
|
|
@ -65,14 +66,14 @@ On each server:
|
|||
prefixed. So the pubkey for server 'mars' would be stored as
|
||||
'server-mars.pub'.
|
||||
|
||||
* copy all keys to **each of** the admin repo clones on your workstation and
|
||||
and add them as usual.
|
||||
* copy all keys to all the admin repo clones on your workstation and and add
|
||||
them as usual. This is an `O(N^2)` operation ;-)
|
||||
|
||||
You may have guessed that the prefix 'server-' is special, and
|
||||
distinguishes a human user from a mirroring peer.
|
||||
|
||||
* create "host" aliases on each machine to refer to all other machines. See
|
||||
[here][ssh-ha] for what/why/how.
|
||||
* create "host" aliases to refer to all other machines. See [here][ssh-ha]
|
||||
for what/how.
|
||||
|
||||
The host alias for a host (in all other machines' `~/.ssh/config` files)
|
||||
MUST be the same as the `HOSTNAME` in the referred host's
|
||||
|
|
@ -108,13 +109,12 @@ On each server:
|
|||
because on the first push to the master it will update all the slaves
|
||||
anyway.
|
||||
|
||||
* when that is all done and tested, **enable mirroring** on each server by
|
||||
going through the rc file and uncommenting all the lines mentioning
|
||||
`Mirroring`.
|
||||
* when that is all done and tested, **enable mirroring** by going through
|
||||
the rc file and uncommenting all the lines mentioning `Mirroring`.
|
||||
|
||||
### conf file settings and syntax
|
||||
|
||||
Mirroring is defined by the following [option][]s. You can have different
|
||||
Mirroring is defined by the following [options][]. You can have different
|
||||
settings for different repos, and of course some repos may not have any mirror
|
||||
options at all -- they are then purely local.
|
||||
|
||||
|
|
|
|||
132
doc/misc.mkd
132
doc/misc.mkd
|
|
@ -1,132 +0,0 @@
|
|||
# odds and ends
|
||||
|
||||
Most of these items don't fit anywhere or fit in more than one place or are of
|
||||
the nature of background information.
|
||||
|
||||
## #include include files
|
||||
|
||||
Gitolite allows you to break up the configuration into multiple files and
|
||||
include them in the main file for convenience.
|
||||
|
||||
include "foo.conf"
|
||||
|
||||
will include the contents of the file "foo.conf" from the "conf" directory.
|
||||
|
||||
Details:
|
||||
|
||||
* You can also use a glob (`include "*.conf"`), or put your include files
|
||||
into subdirectories of "conf" (`include "foo/bar.conf"`), or both
|
||||
(`include "repos/*.conf"`).
|
||||
|
||||
* Included files are always searched relative to the gitolite-admin repo's
|
||||
"conf/" directory.
|
||||
|
||||
* If you ended up recursing, files that have been already processed once are
|
||||
skipped, with a warning.
|
||||
|
||||
<font color="gray">Advanced users: `subconf`, a command that is very closely
|
||||
related to `include`, is documented [here][subconf].</font>
|
||||
|
||||
## #deny-rules applying deny rules at the pre-git access check
|
||||
|
||||
The access [rules][] rules section describes the problem. To recap, you want
|
||||
this:
|
||||
|
||||
@staff = alice bob wally ashok
|
||||
|
||||
repo foo
|
||||
RW+ = alice # line 1
|
||||
RW+ dev = bob # line 2
|
||||
- = wally # line 3
|
||||
RW temp/ = @staff # line 4
|
||||
|
||||
to deny Wally even *read* access.
|
||||
|
||||
The way to do this is to add this line to the repo:
|
||||
|
||||
option deny-rules = 1
|
||||
|
||||
If you want this for all your repos, just add this somewhere at the top of
|
||||
your conf file
|
||||
|
||||
repo @all
|
||||
option deny-rules = 1
|
||||
|
||||
## #rule-accum rule accumulation
|
||||
|
||||
Gitolite was meant to collect rules from multiple places and apply them all.
|
||||
For example, this:
|
||||
|
||||
repo foo
|
||||
RW = u1
|
||||
|
||||
@gr1 = foo bar
|
||||
|
||||
repo @gr1
|
||||
RW = u2
|
||||
R = u3
|
||||
|
||||
repo @all
|
||||
R = gitweb
|
||||
|
||||
is effectively the same as this, for repo foo:
|
||||
|
||||
repo foo
|
||||
RW = u1
|
||||
RW = u2
|
||||
R = u3
|
||||
R = gitweb
|
||||
|
||||
This extends to patterns also, but I'll leave an example for later.
|
||||
|
||||
## #subconf the subconf command
|
||||
|
||||
This is just like the include command:
|
||||
|
||||
subconf "foo/bar.conf" # example 1
|
||||
subconf "foo/*.conf" # example 2
|
||||
|
||||
with the difference that, for the duration of the file(s) being included, a
|
||||
subconf restriction is in effect. This restrictions limits the repos that can
|
||||
be access controlled by the lines within the included file(s).
|
||||
|
||||
Here's how it works. First, a subconf *name* is derived from the filename
|
||||
being included, which is basically the basename of the file. For example 1
|
||||
that is "bar". For example 2, assuming foo contains "a.conf" and "b.conf",
|
||||
the subconf name is "a" while processing "a.conf", and "b" while processing
|
||||
"b.conf".
|
||||
|
||||
A variation of the subconf command allows you to specify the subconf *name*
|
||||
explicitly, while including files as before:
|
||||
|
||||
subconf frob "foo/bar.conf # example 3
|
||||
subconf frob "foo/*.conf # example 4
|
||||
|
||||
In this case the subconf name is "frob" in both cases.
|
||||
|
||||
A subconf restricts the repos that can be named in 'repo' lines while the
|
||||
subconf is in effect. If the subconf name is "foo", the conf lines parsed
|
||||
while under the subconf restriction can only refer to
|
||||
|
||||
* a repo called 'foo'
|
||||
* a repo group called '@foo'
|
||||
* the members of the same repo group '@foo'
|
||||
* match a regex that is a member of the repo group '@foo'
|
||||
|
||||
In the last 3 cases, the repo group '@foo' must be defined in the main conf
|
||||
file (i.e., outside the subconf restriction).
|
||||
|
||||
For example, if you have this in the main conf file:
|
||||
|
||||
@foo = bar baz frob/..*
|
||||
|
||||
subconf "foo.conf"
|
||||
|
||||
then foo.conf can only refer to 'foo', '@foo', 'bar', 'baz', or any repo name
|
||||
matching the pattern `frob/..*`.
|
||||
|
||||
## #HOSTNAME HOSTNAME substitution
|
||||
|
||||
Wherever gitolite sees the word `%HOSTNAME`, it will replace it with the
|
||||
HOSTNAME supplied in the rc file, if one was supplied. This is mainly useful
|
||||
in [mirroring][].
|
||||
16
doc/mkdoc
16
doc/mkdoc
|
|
@ -13,6 +13,8 @@ use Tsh;
|
|||
$ENV{TSH_ERREXIT} = 1;
|
||||
|
||||
try "
|
||||
./fm2mt.pl < g3-master-toc.mm > master-toc.mkd
|
||||
|
||||
mkdir ../html; ok
|
||||
git status -s -uno; !/./
|
||||
git log --oneline -1
|
||||
|
|
@ -36,8 +38,8 @@ try "
|
|||
" or die 2;
|
||||
|
||||
sub main {
|
||||
chomp(@ARGV = `cat list`) if not @ARGV;
|
||||
@ARGV = grep { $_ ne 'master-toc.mkd' and /./ } @ARGV;
|
||||
chomp(@ARGV = `find . -name "*.mkd" | cut -c3-`) if not @ARGV;
|
||||
@ARGV = grep { /./ } @ARGV;
|
||||
my @save = @ARGV;
|
||||
my $css = join("", <DATA>);
|
||||
|
||||
|
|
@ -68,16 +70,16 @@ sub main {
|
|||
}
|
||||
}
|
||||
|
||||
open($fh, ">", "master-toc.mkd")
|
||||
and print $fh $mt
|
||||
and close $fh;
|
||||
# open($fh, ">", "master-toc.mk2")
|
||||
# and print $fh $mt
|
||||
# and close $fh;
|
||||
|
||||
# after this, do this for every mkd (including the master-toc.mkd)
|
||||
|
||||
# cat $css_block > $base.html
|
||||
# cat $base.mkd $mf | $MKD >> $base.html
|
||||
|
||||
for my $mkd ("master-toc.mkd", @save) {
|
||||
for my $mkd (@save) {
|
||||
$mkd =~ /^(?:.*\/)?([^\/]+)\.mkd$/;
|
||||
my $b = $1;
|
||||
|
||||
|
|
@ -88,7 +90,7 @@ sub main {
|
|||
my $mkt = `cat $mkd`;
|
||||
$mkt =~ s/^(#+) #(\S+) /$1 <a name="$2"><\/a> /mg;
|
||||
open($fh, "|-", "$MKD >> ../html/$b.html")
|
||||
and print $fh $mkt, $mf
|
||||
and print $fh $mkt, "\n\n", $mf
|
||||
and close $fh;
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ A list of these commands can be obtained by running `gitolite help` on the
|
|||
server. A different (and probably much smaller) list can be obtained by a
|
||||
remote user running `ssh git@host help`.
|
||||
|
||||
All the commands will respond to `-h`; please report a bug to me if they
|
||||
don't.
|
||||
All the commands that ship with gitolite will respond to `-h`; please report a
|
||||
bug to me if they don't.
|
||||
|
||||
## syntactic sugar
|
||||
|
||||
|
|
@ -43,7 +43,7 @@ The `POST_GIT` triggers are:
|
|||
The `POST_COMPILE` triggers are:
|
||||
|
||||
* post-compile/ssh-authkeys -- takes the pubkeys in keydir and populates
|
||||
`~/.ssh/authorized_keys`
|
||||
`~/.ssh/authorized_keys`.
|
||||
|
||||
* post-compile/update-git-configs -- updates individual 'repo.git/config'
|
||||
files (using the 'git config ...' command) from settings supplied in the
|
||||
|
|
@ -52,7 +52,7 @@ The `POST_COMPILE` triggers are:
|
|||
|
||||
* post-compile/update-git-daemon-access-list -- create/delete
|
||||
'git-daemon-export-ok' files in each repo based on whether the conf says
|
||||
'daemon' can read the repo or not
|
||||
'daemon' can read the repo or not.
|
||||
|
||||
* post-compile/update-gitweb-access-list -- populates the file named in
|
||||
`GITWEB_PROJECTS_LIST` in the rc file (default: `$HOME/projects.list`)
|
||||
|
|
@ -60,7 +60,7 @@ The `POST_COMPILE` triggers are:
|
|||
more than just "R = gitweb"; any repo that has any config setting with the
|
||||
section name 'gitweb' (like 'gitweb.owner', 'gitweb.description', etc) is
|
||||
considered readable by gitweb, so the final list is a union of these two
|
||||
methods
|
||||
methods.
|
||||
|
||||
The `POST_CREATE` triggers are:
|
||||
|
||||
|
|
@ -69,56 +69,11 @@ The `POST_CREATE` triggers are:
|
|||
|
||||
## VREFs
|
||||
|
||||
You should read about [vref][]s in detail first; this won't make sense
|
||||
otherwise. For a brief recap, note that there are 2 kinds of VREFs: those
|
||||
that require arguments and those that behave just like any other `update`
|
||||
hook.
|
||||
|
||||
COUNT is an example of the former (hence the long-ish description). DUPKEYS
|
||||
and EMAIL-CHECK are both examples of the latter.
|
||||
|
||||
* COUNT
|
||||
|
||||
The COUNT VREF is used like this:
|
||||
|
||||
- VREF/COUNT/9 = @junior-developers
|
||||
|
||||
In response, if anyone in the user list pushes a commit series that
|
||||
changes more than 9 files, a vref of "VREF/COUNT/9" is returned. Gitolite
|
||||
uses that as a "ref" to match against all the rules, hit the same rule
|
||||
that invoked it, and deny the request.
|
||||
|
||||
If the user did not push more than 9 files, the VREF code returns nothing,
|
||||
and nothing happens.
|
||||
|
||||
COUNT can take one more argument:
|
||||
|
||||
- VREF/COUNT/9/NEWFILES = @junior-developers
|
||||
|
||||
This is the same as before, but have to be more than 9 *new* files not
|
||||
just changed files.
|
||||
|
||||
* DUPKEYS -- this checks keydir/ for duplicate keys and aborts the push if
|
||||
it finds any. You should use this only on the gitolite-admin repo.
|
||||
|
||||
repo gitolite-admin
|
||||
- VREF/DUPKEYS = @all
|
||||
|
||||
* EMAIL-CHECK -- read the comments in the code for this one. Like DUPKEYS,
|
||||
it does not take any arguments.
|
||||
|
||||
* FILETYPE -- this is sample code for a very site-specific purpose; you'll
|
||||
have to read the code
|
||||
|
||||
* MERGE-CHECK -- this is sample code to illustrate how one of the gitolite
|
||||
built-in functions *could* have been handled, although there are some
|
||||
differences
|
||||
|
||||
* partial-copy -- this has its own section later in this page
|
||||
VREFs have their [own page][vref].
|
||||
|
||||
## special cases
|
||||
|
||||
### partial-copy
|
||||
### #partial-copy partial-copy
|
||||
|
||||
Git (and therefore gitolite) cannot do selective read control -- allowing
|
||||
someone to read branch A but not branch B. It's the entire repo or nothing.
|
||||
|
|
@ -155,6 +110,6 @@ WARNINGS:
|
|||
you should delete the partial repo on the server and then run 'gitolite
|
||||
compile' to let it build again. See t/partial-copy.t for details.
|
||||
|
||||
* not tested with smart http; probabl won't work
|
||||
* not tested with smart http; probably won't work
|
||||
|
||||
* also not tested with mirroring, or with wild card repos.
|
||||
|
|
|
|||
20
doc/options.mkd
Normal file
20
doc/options.mkd
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# gitolite options
|
||||
|
||||
Some gitolite features are enabled, or gitolite's behaviour changed, by
|
||||
setting "options".
|
||||
|
||||
Options are set by repo. The syntax is very simple:
|
||||
|
||||
option foo.bar = baz
|
||||
|
||||
Of course this is useless if some other part of gitolite, or some external
|
||||
command, is not querying for the option key 'foo.bar'!
|
||||
|
||||
Options are therefore documented in the section/page they belong in, not here.
|
||||
Here are the currently recognised options:
|
||||
|
||||
* [deny-rules][] -- ask gitolite to honor deny rules during the pre-git
|
||||
check also.
|
||||
|
||||
* [mirroring][] related options -- tell gitolite who is the master server,
|
||||
and who are the slaves, for each repo.
|
||||
45
doc/pw.mkd
45
doc/pw.mkd
|
|
@ -1,45 +0,0 @@
|
|||
# patches welcome :-)
|
||||
|
||||
These are places where I could use some help, with hints about how you would
|
||||
go about it. In addition, any of the items in [dev-status][] are up for
|
||||
grabs, if you wish to jump in. But let me know before you start, and how you
|
||||
plan to go about it.
|
||||
|
||||
## #pw2 rsync
|
||||
|
||||
The crux of the old rsync ADC was an access check to a repo whose name starts
|
||||
with EXTCMD. g2 would treat repos whose names start with EXTCMD as "don't
|
||||
create this repo". g3 makes no such distinctions, but you can get the same
|
||||
effect by using a repo group name that does not exist:
|
||||
|
||||
repo @rsync-set1
|
||||
...rules...
|
||||
|
||||
and check that in the script. (It might mean adding one more function to
|
||||
Gitolite::Easy but that's... easy!)
|
||||
|
||||
## #pw1 converting non-openssh pubkeys automatically
|
||||
|
||||
Gitolite's [triggers][] has can be used to fix this. Here's pseudo-code:
|
||||
|
||||
chdir $(gitolite query-rc -n GL_ADMIN_BASE)/keydir
|
||||
for each *.pub file in this directory and its subdirectories
|
||||
detect its format and convert it
|
||||
# just overwrite it; the original is saved in git anyway
|
||||
|
||||
Let's say the program is called "convert-non-openssh-keys". You send it to me
|
||||
and I add it to src/commands/post-compile/. Then I update the default rc file
|
||||
to look at least like this instead
|
||||
|
||||
POST_COMPILE =>
|
||||
[
|
||||
# 'post-compile/convert-non-openssh-keys',
|
||||
'post-compile/ssh-authkeys',
|
||||
...
|
||||
...
|
||||
],
|
||||
|
||||
making sure to place it *before* ssh-authkeys, and anyone who needs it can
|
||||
just uncomment it.
|
||||
|
||||
Done!
|
||||
53
doc/qi.mkd
53
doc/qi.mkd
|
|
@ -1,26 +1,45 @@
|
|||
# getting started
|
||||
# quick install, setup, and clone
|
||||
|
||||
The quickest install, assuming your `$PATH` contains `$HOME/bin`, is:
|
||||
(Please do not ignore the "assumptions" list below).
|
||||
|
||||
* get the software
|
||||
On the server:
|
||||
|
||||
git clone git://github.com/sitaramc/gitolite
|
||||
# get the software
|
||||
git clone -b g3 git://github.com/sitaramc/gitolite
|
||||
|
||||
# (until this becomes "master")
|
||||
cd gitolite
|
||||
git checkout -f g3
|
||||
|
||||
* install it
|
||||
|
||||
ln -sf $PWD/src/gitolite $HOME/bin
|
||||
|
||||
If you don't like that, there are [other install methods][install].
|
||||
|
||||
Once the install is done, setup:
|
||||
# install it
|
||||
gitolite/install -ln
|
||||
|
||||
# setup the initial repos with your key
|
||||
gitolite setup -pk your-name.pub
|
||||
|
||||
And that's it.
|
||||
On your workstation:
|
||||
|
||||
Next steps are usually [adding][add] users and repos and learning about
|
||||
# clone the admin repo so you can start adding stuff
|
||||
git clone git@host:gitolite-admin.git
|
||||
|
||||
## ASSUMPTIONS
|
||||
|
||||
* on the server, your `$PATH` contains `$HOME/bin`. If you don't like that,
|
||||
there are [other install methods][install].
|
||||
|
||||
* "your-name.pub" is your public key from your workstation.
|
||||
* also, this key does not already have shell access to this gitolite
|
||||
hosting user
|
||||
|
||||
* the setup command does not generate any warnings.
|
||||
* if it does, please see [common errors][ce] and fix things before
|
||||
continuing, or read the more complete [setup][] page.
|
||||
|
||||
## Notes
|
||||
|
||||
Note that the clone path is NOT "repositories/gitolite-admin.git". If you
|
||||
clone with a path that includes "repositories/", the clone should fail. If
|
||||
the clone *does* succeed, a subsequent push should fail :-) See
|
||||
[this][ybpfail] for some details. If that doesn't make enough sense read all
|
||||
of [ssh][].
|
||||
|
||||
## next steps
|
||||
|
||||
Next steps are usually adding [users][] and [repos][] and learning about
|
||||
[access control][conf].
|
||||
|
|
|
|||
41
doc/rare.mkd
Normal file
41
doc/rare.mkd
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# rare or one-time activities
|
||||
|
||||
## #existing moving existing repos into gitolite
|
||||
|
||||
* move the repos to `$HOME/repositories`. Make sure they are all *bare*
|
||||
repos, and the directory names end in ".git".
|
||||
|
||||
* [add them][repos] to conf/gitolite.conf in your clone of the admin repo,
|
||||
then commit and push the change.
|
||||
|
||||
If the repos are already covered by some [wild][] pattern, this is
|
||||
optional.
|
||||
|
||||
* run `gitolite setup` to fix up the hooks on all repos, just in case.
|
||||
|
||||
## #moving moving servers
|
||||
|
||||
This is adapted from the "migrating" section of the [install][] page; if
|
||||
you're actually *migrating* from g2 please go there!
|
||||
|
||||
Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
|
||||
any repository except the gitolite-admin repo. The only thing it will
|
||||
normally touch is the `update` hook. So one fool-proof way of "moving"
|
||||
servers is this (untested but should work; feedback appreciated):
|
||||
|
||||
1. Install gitolite on the new server, using the same key for the admin as
|
||||
for the old server.
|
||||
|
||||
2. Copy the [rc][] file from the old server, overwriting this one.
|
||||
|
||||
3. [Disable][writable] the old server so people won't push to it.
|
||||
|
||||
4. Copy all the repos over from the old server, including gitolite-admin.
|
||||
Make sure the files end up with right ownership and permissions; if not,
|
||||
chown/chmod them.
|
||||
|
||||
5. On a clone of the old gitolite-admin, add a new remote (or change an
|
||||
existing one) to point to the new server. Then `git push -f` to this
|
||||
remote.
|
||||
|
||||
6. On the server, run `gitolite setup`.
|
||||
82
doc/rc.mkd
82
doc/rc.mkd
|
|
@ -1,20 +1,82 @@
|
|||
# the "rc" file ($HOME/.gitolite.rc)
|
||||
# the "rc" file (`$HOME/.gitolite.rc`)
|
||||
|
||||
The rc file for g3 is quite different from that of g2. It has been designed
|
||||
to be (a) the only thing unique to your site, for most installations and (b)
|
||||
easy to extend when new needs show up, without having to touch core gitolite.
|
||||
**NOTE**: if you're migrating from g2, there are some settings that MUST be
|
||||
dealt with **before** running `gitolite setup`; please read the [g2
|
||||
migration][g2migr] page and linked pages, and especially the one on
|
||||
[presetting the rc file][rc-preset].
|
||||
|
||||
g2 had a nasty rc file where every variable had to be declared. As a result,
|
||||
ADCs that needed their own settings could not use it.
|
||||
----
|
||||
|
||||
Now it's a perl hash, and you can add any keys you want.
|
||||
The rc file for g3 is *quite* different from that of g2.
|
||||
|
||||
Please look at the rc file that gets installed when you setup gitolite. As
|
||||
you can see there are 3 types of variables in it:
|
||||
As before, it is designed to be the only thing unique to your site for most
|
||||
setups. What is new is that it is easy to extend it when new needs come up,
|
||||
without having to touch core gitolite.
|
||||
|
||||
The rc file is perl code, but you do NOT need to know perl to edit it. Just
|
||||
mind the commas, use single quotes unless you know what you're doing, and make
|
||||
sure the brackets and braces stay matched up!
|
||||
|
||||
Please look at the `~/.gitolite.rc` file that gets installed when you setup
|
||||
gitolite. As you can see there are 3 types of variables in it:
|
||||
|
||||
* simple variables (like UMASK)
|
||||
* lists (like `POST_COMPILE`, `POST_CREATE`)
|
||||
* hashes (like `ROLES`, `COMMANDS`)
|
||||
|
||||
While some of the variables are documented in this file, many of them are not.
|
||||
Their purposes are to be found in each of their individual documentation files
|
||||
around; start with [customising gitolite][cust].
|
||||
around; start with [customising gitolite][cust]. If a setting is used by an
|
||||
external command then running that command with '-h' may give you additional
|
||||
information.
|
||||
|
||||
## specific variables
|
||||
|
||||
* `$UMASK`, octal, default `0077`
|
||||
|
||||
The default UMASK that gitolite uses makes all the repos and their
|
||||
contents have `rwx------` permissions. People who want to run gitweb
|
||||
realise that this will not do.
|
||||
|
||||
The correct way to deal with this is to give this variable a value like
|
||||
`0027` (note the syntax: the leading 0 is required), and then make the
|
||||
user running the webserver (apache, www-data, whatever) a member of the
|
||||
'git' group.
|
||||
|
||||
If you've already installed gitolite then existing files will have to be
|
||||
fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
|
||||
This is because umask only affects permissions on newly created files, not
|
||||
existing ones.
|
||||
|
||||
* `$GIT_CONFIG_KEYS`, string, default empty
|
||||
|
||||
This setting allows the repo admin to define acceptable gitconfig keys.
|
||||
|
||||
Gitolite allows you to set git config values using the "config" keyword;
|
||||
see [here][git-config] for details and syntax.
|
||||
|
||||
However, if you are in an installation where the repo admin does not (and
|
||||
should not) have shell access to the server, then allowing him to set
|
||||
arbitrary repo config options *may* be a security risk -- some config
|
||||
settings allow executing arbitrary commands!
|
||||
|
||||
You have 3 choices. By default `$GIT_CONFIG_KEYS` is left empty, which
|
||||
completely disables this feature (meaning you cannot set git configs via
|
||||
the repo config).
|
||||
|
||||
The second choice is to give it a space separated list of settings you
|
||||
consider safe. (These are actually treated as a set of [regular
|
||||
expression][regex] patterns, and any one of them must match).
|
||||
|
||||
For example:
|
||||
|
||||
$GIT_CONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';
|
||||
|
||||
Each pattern should match the *whole* key (in other words, there
|
||||
is an implicit `^` at the start of each pattern, and a `$` at the
|
||||
end).
|
||||
|
||||
The third choice (which you may have guessed already if you're familiar
|
||||
with regular expressions) is to allow anything and everything:
|
||||
`$GIT_CONFIG_KEYS = '.*';`
|
||||
|
||||
|
|
|
|||
|
|
@ -3,11 +3,15 @@
|
|||
A refex is a word I made up to mean "a regex that matches a ref". If you know
|
||||
[regular expressions][regex] you're halfway there.
|
||||
|
||||
The only extra info you need is:
|
||||
In addition:
|
||||
|
||||
* for convenience, a refex not starting with `refs/` is assumed to start
|
||||
with `refs/heads/`. This means normal branches can be referred to like
|
||||
this:
|
||||
* if no refex is supplied, it defaults to `refs/.*`, for example in a rule
|
||||
like this:
|
||||
|
||||
RW = alice
|
||||
|
||||
* a refex not starting with `refs/` is assumed to start with `refs/heads/`.
|
||||
This means normal branches can be conveniently written like this:
|
||||
|
||||
RW master = alice
|
||||
# becomes 'refs/heads/master' internally
|
||||
|
|
@ -18,13 +22,13 @@ The only extra info you need is:
|
|||
|
||||
* a refex is implicitly anchored at the start, but not at the end. In
|
||||
regular expression lingo, a `^` is assumed at the start (but no `$` at the
|
||||
end is assumed). So a refex of `master` will allow all these:
|
||||
end is assumed). So a refex of `master` will match all these:
|
||||
|
||||
refs/heads/master
|
||||
refs/heads/master1
|
||||
refs/heads/master2
|
||||
refs/heads/master/full
|
||||
|
||||
If you want to restrict to just the one specific ref, use
|
||||
If you want to restrict the match to just the one specific ref, use
|
||||
|
||||
RW master$ = alice
|
||||
|
|
|
|||
23
doc/repo.mkd
23
doc/repo.mkd
|
|
@ -1,23 +0,0 @@
|
|||
## #repo repo definitions
|
||||
|
||||
Example:
|
||||
|
||||
repo gitolite tsh gitpod
|
||||
RW+ = sitaram
|
||||
RW dev = alice bob
|
||||
R = @all
|
||||
|
||||
The "repo" line can have any number of repo names or repo group names in it.
|
||||
However, it can only be one line; this will not work
|
||||
|
||||
repo foo
|
||||
repo bar # WRONG; 'foo' is now forgotten
|
||||
RW = alice
|
||||
|
||||
If you have too many, use a group name:
|
||||
|
||||
@myrepos = foo
|
||||
@myrepos = bar
|
||||
|
||||
repo @myrepos
|
||||
RW = alice
|
||||
53
doc/repos.mkd
Normal file
53
doc/repos.mkd
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
# adding and removing repos
|
||||
|
||||
> ----
|
||||
|
||||
> *WARNING: Do NOT add repos directly on the server. Clone the
|
||||
> 'gitolite-admin' repo to your workstation, make changes to it, then add,
|
||||
> commit, and push. When the push hits the server, the server "acts" upon
|
||||
> your changes.*
|
||||
|
||||
> ----
|
||||
|
||||
Just as for [users][], all operations are in a clone of the gitolite-admin
|
||||
repo.
|
||||
|
||||
To **add** a new repo, edit `conf/gitolite.conf` and add it, along with at
|
||||
least one user with some permissions. Or add it to an existing repo line:
|
||||
|
||||
repo gitolite tsh gitpod
|
||||
RW+ = sitaram
|
||||
RW dev = alice bob
|
||||
R = @all
|
||||
|
||||
The "repo" line can have any number of repo names or repo group names in it.
|
||||
However, it can only be one line; this will not work
|
||||
|
||||
repo foo
|
||||
repo bar # WRONG; 'foo' is now forgotten
|
||||
RW = alice
|
||||
|
||||
If you have too many, use a group name:
|
||||
|
||||
@myrepos = foo
|
||||
@myrepos = bar
|
||||
|
||||
repo @myrepos
|
||||
RW = alice
|
||||
|
||||
Finally, you add, commit, and push this change. Gitolite will create a bare,
|
||||
empty, repo on the server that is ready to be cloned.
|
||||
|
||||
**Removing** a repo is not so straightforward. You certainly must remove the
|
||||
appropriate lines from the `conf/gitolite.conf` file, but gitolite will not
|
||||
automatically delete the repo from the server. You have to log on to the
|
||||
server and do the dirty deed yourself :-)
|
||||
|
||||
It is best to make the change in the conf file, push it, and *then* go to the
|
||||
server and do what you need to.
|
||||
|
||||
**Renaming** a repo is also not automatic. Here's what you do (and the order
|
||||
is important):
|
||||
|
||||
* go to the server and rename the repo at the Unix command line
|
||||
* change the name in the conf/gitolite.conf file and add/commit/push.
|
||||
|
|
@ -15,7 +15,28 @@ We will use this as a running example:
|
|||
RW temp/ = @staff # line 4
|
||||
R = ashok # line 5
|
||||
|
||||
### when does gitolite check access
|
||||
### what does a rule look like?
|
||||
|
||||
A rule line has the structure
|
||||
|
||||
<permission> <zero or more refexes> = <one or more users/user groups>
|
||||
|
||||
The most common permissions used are:
|
||||
|
||||
* R, for read only
|
||||
* RW, for push existing ref or create new ref
|
||||
* RW+, for "push -f" or ref deletion allowed (i.e., destroy
|
||||
information)
|
||||
* `-` (the minus sign), to **deny** access.
|
||||
|
||||
There are also other, less commonly used, [types of permissions][write-types].
|
||||
|
||||
A refex is an expression that matches the ref (i.e., branch or tag) being
|
||||
pushed. See [this][refex] for more info.
|
||||
|
||||
### when are the rules checked?
|
||||
|
||||
There are 2 places where access rules are checked.
|
||||
|
||||
The "pre-git" check is before git is invoked. Gitolite knows the repo name,
|
||||
user name, and attempted access (R or W), but no ref name.
|
||||
|
|
@ -23,7 +44,7 @@ user name, and attempted access (R or W), but no ref name.
|
|||
The "update" check is only for write operations, and it is just before git
|
||||
updates a ref. This time gitolite knows the refname also.
|
||||
|
||||
### how is a particular rule line matched
|
||||
### how are the rules matched?
|
||||
|
||||
For the **pre-git check**, any permission that contains "R" matches a read
|
||||
operation, and any permission that contains "W" matches a write operation.
|
||||
|
|
@ -39,8 +60,8 @@ For the **update check**, git gives us all the information we need. Then:
|
|||
|
||||
* all the rules for a repo are [accumulated][rule-accum]
|
||||
|
||||
* then the rules pertaining to this repo *and* this user (or to a group to
|
||||
which they belong, respectively) are kept; the rest are ignored
|
||||
* the rules pertaining to this repo *and* this user (or to a group to which
|
||||
they belong, respectively) are kept; the rest are ignored
|
||||
|
||||
* these rules are examined *in the sequence they appeared in the conf file*.
|
||||
For each rule:
|
||||
|
|
@ -73,10 +94,58 @@ deny rules for pre-git, but having got past it, he can't actually do anything.
|
|||
That's by design, and as I said if you don't like it you can ask gitolite to
|
||||
[deny at pre-git][deny-rules].
|
||||
|
||||
### summary of permissions
|
||||
### #perms summary of permissions
|
||||
|
||||
The full set of permissions, in regex syntax: `-|R|RW+?C?D?M?`. This expands
|
||||
to one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
|
||||
`RW+CD`, all but the first one optionally followed by an `M`. And by now you
|
||||
`RW+CD`, all but the first two optionally followed by an `M`. And by now you
|
||||
know what they all mean.
|
||||
|
||||
## additional topics
|
||||
|
||||
### #rule-accum rule accumulation
|
||||
|
||||
Gitolite was meant to collect rules from multiple places and apply them all.
|
||||
For example, this:
|
||||
|
||||
repo foo
|
||||
RW = u1
|
||||
|
||||
@gr1 = foo bar
|
||||
|
||||
repo @gr1
|
||||
RW = u2
|
||||
R = u3
|
||||
|
||||
repo @all
|
||||
R = gitweb
|
||||
|
||||
is effectively the same as this, for repo foo:
|
||||
|
||||
repo foo
|
||||
RW = u1
|
||||
RW = u2
|
||||
R = u3
|
||||
R = gitweb
|
||||
|
||||
This extends to patterns also, but I'll leave an example for later.
|
||||
|
||||
### #deny-rules applying deny rules during the pre-git check
|
||||
|
||||
The access rules section above describes the problem in one scenario. Here's
|
||||
another. Let's say you have this at the end of your gitolite.conf file:
|
||||
|
||||
repo @all
|
||||
R = gitweb daemon
|
||||
|
||||
but you don't want the gitolite-admin repo showing up on gitweb. How do you
|
||||
do that? Here's how:
|
||||
|
||||
repo gitolite-admin
|
||||
- = gitweb daemon
|
||||
option deny-rules = 1
|
||||
|
||||
repo @all
|
||||
R = gitweb daemon
|
||||
|
||||
Note that the order matters; the `-` rule must come *before* the `R` rule.
|
||||
|
|
|
|||
41
doc/setup.mkd
Normal file
41
doc/setup.mkd
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# setting up gitolite
|
||||
|
||||
Installing the software gets you ready to use it, but the first "use" of it is
|
||||
always the "setup" command.
|
||||
|
||||
The first time you run it, you need to have a public key file ready. If the
|
||||
main gitolite admin's username is "alice", this file should be named
|
||||
"alice.pub". Then run
|
||||
|
||||
gitolite setup -pk alice.pub
|
||||
|
||||
If that command completes without any warnings, you should be done. If it had
|
||||
a warning, you probably supplied a key which already has shell access to the
|
||||
server. That won't work.
|
||||
|
||||
> ----
|
||||
|
||||
> Normally, gitolite is hosted on a user that no one accesses directly --
|
||||
> you log on to the server using some other userid, and then `su - git`. In
|
||||
> this scenario, there *is* no key being used for shell access, so there is
|
||||
> no conflict.
|
||||
|
||||
> An alternative method is to use two different keys, and a [host
|
||||
> alias][ssh-ha] to distinguish the two.
|
||||
|
||||
> [common errors][ce] has some links to background information on this
|
||||
> issue.
|
||||
|
||||
> ----
|
||||
|
||||
The 'setup' command has other uses, so you will be running it at other times
|
||||
after the install as well:
|
||||
|
||||
* to setup the update hook when you move [existing][] repos to gitolite.
|
||||
This also applies if someone has been fiddling with the hooks on some
|
||||
repos and you want to put them all right quickly.
|
||||
|
||||
* to replace a [lost admin key][lost-key].
|
||||
|
||||
When in doubt, run 'gitolite setup' anyway; it doesn't do any harm, though it
|
||||
may take a minute or so if you have more than a few thousand repos!
|
||||
42
doc/special.mkd
Normal file
42
doc/special.mkd
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# special features and setups
|
||||
|
||||
## #writable disabling pushes to take backups
|
||||
|
||||
The `writable` command allows you to disable pushes to all repos or just the
|
||||
named repo, in order to do file-system level things to the repo directory that
|
||||
require it not to change, like using normal backup software.
|
||||
|
||||
Run `gitolite writable -h` for more info.
|
||||
|
||||
## #pers "personal" branches
|
||||
|
||||
"personal" branches are great for environments where developers need to share
|
||||
work but can't directly pull from each other (usually due to either a
|
||||
networking or authentication related reason, both common in corporate setups).
|
||||
|
||||
Personal branches exist **in a namespace** of their own. The syntax is
|
||||
|
||||
RW+ personal/USER/ = @userlist
|
||||
|
||||
where the "personal" can be anything you like (but cannot be empty), and the
|
||||
"/USER/" part is **necessary (including both slashes)**.
|
||||
|
||||
A user "alice" (if she's in the userlist) can then push any branches inside
|
||||
`personal/alice/`. Which means she can push `personal/alice/foo` and
|
||||
`personal/alice/bar`, but NOT `personal/alice`.
|
||||
|
||||
(Background: at runtime the "USER" component will be replaced by the name of
|
||||
the invoking user. Access is determined by the right hand side, as usual).
|
||||
|
||||
Compared to using arbitrary branch names on the same server, this
|
||||
|
||||
* reduces namespace pollution by corralling all these ad hoc branches into
|
||||
the "personal/" namespace.
|
||||
* reduces branch name collision by giving each developer her own
|
||||
sub-hierarchy within that.
|
||||
* removes the need to think about access control, because a user can push
|
||||
only to his own sub-hierarchy.
|
||||
|
||||
## delegating access control responsibilities
|
||||
|
||||
See [this][deleg].
|
||||
46
doc/syntax.mkd
Normal file
46
doc/syntax.mkd
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# #syntax basic syntax
|
||||
|
||||
In general, everything is **space separated**; there are no commas,
|
||||
semicolons, etc., in the syntax.
|
||||
|
||||
**Comments** are in the usual shell-ish style.
|
||||
|
||||
**User names** and **repo names** are as simple as possible; they must start
|
||||
with an alphanumeric, but after that they can also contain `.`, `_`, or `-`.
|
||||
|
||||
Usernames can optionally be followed by an `@` and a domainname containing at
|
||||
least one `.` (this allows you to use an email address as someone's username).
|
||||
Reponames can contain `/` characters (this allows you to put your repos in a
|
||||
tree-structure for convenience)
|
||||
|
||||
There are no continuation lines by default. You do not need them; the section
|
||||
on "groups" will tell you how you can break up large lists of names in a group
|
||||
definition into multiple lines.
|
||||
|
||||
<font color="gray">If you *must* have them, you can optionally enable them;
|
||||
see the syntactic [sugar][] section.</font>
|
||||
|
||||
## #include include files
|
||||
|
||||
Gitolite allows you to break up the configuration into multiple files and
|
||||
include them in the main file for convenience.
|
||||
|
||||
include "foo.conf"
|
||||
|
||||
will include the contents of the file "foo.conf".
|
||||
|
||||
Details:
|
||||
|
||||
* You can also use a glob (`include "*.conf"`), or put your include files
|
||||
into subdirectories of "conf" (`include "foo/bar.conf"`), or both
|
||||
(`include "repos/*.conf"`).
|
||||
|
||||
* Included files are always searched from the gitolite-admin repo's "conf/"
|
||||
directory, unless you supplied an absolute path. (Note: in the interests
|
||||
of cloning the admin-repo sanely you should avoid absolute paths!)
|
||||
|
||||
* If you ended up recursing, files that have been already processed once are
|
||||
skipped, with a warning.
|
||||
|
||||
<font color="gray">Advanced users: `subconf`, a command that is very closely
|
||||
related to `include`, is documented [here][subconf].</font>
|
||||
|
|
@ -1,7 +1,9 @@
|
|||
# testing gitolite
|
||||
|
||||
Here's how to *run* the tests. **WARNING: they will clobber lots of things in
|
||||
your `$HOME`, so be sure to use a throwaway userid**.
|
||||
Here's how to *run* the tests.
|
||||
|
||||
<font color="red">**WARNING: they will clobber lots of things in your `$HOME`,
|
||||
so be sure to use a throwaway userid**.</font>
|
||||
|
||||
git clone git://github.com/sitaramc/gitolite
|
||||
cd gitolite
|
||||
|
|
@ -21,7 +23,3 @@ would otherwise take.
|
|||
|
||||
If you think that defeats the purpose of the testing, you haven't read
|
||||
[this][auth] yet.
|
||||
|
||||
There are 2 specific tests that deal with ssh though, which are run only on
|
||||
request, as you can see above, because they clobber your `~/.ssh`. You have
|
||||
been warned.
|
||||
|
|
|
|||
|
|
@ -50,15 +50,16 @@ Triggers receive the following arguments:
|
|||
command in the PRE_GIT trigger sequence),
|
||||
|
||||
2. the name of the trigger as a string (example, `"POST_COMPILE"`), so you
|
||||
can call the same program from multiple triggers and know where it was
|
||||
called from,
|
||||
can call the same program from multiple triggers and it can know where it
|
||||
was called from,
|
||||
|
||||
3. followed by zero or more arguments specific to the trigger, as given in
|
||||
the next section.
|
||||
|
||||
## trigger-specific details
|
||||
## trigger-specific arguments and other details
|
||||
|
||||
Here's a brief "when" and "with what arguments" for each trigger.
|
||||
Here are the **rest of** the arguments for each trigger, plus a brief
|
||||
description of when the trigger runs:
|
||||
|
||||
* `ACCESS_1` runs after the first access check. Arguments:
|
||||
* repo
|
||||
|
|
|
|||
95
doc/user.mkd
Normal file
95
doc/user.mkd
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
# what users (not admins) need to know about gitolite
|
||||
|
||||
...written for the one guy in the world no one will think of as "just a normal
|
||||
user" ;-)
|
||||
|
||||
This document has some text, and a lot of links. Most of this info *is*
|
||||
available in the rest of the documentation, but it's scattered and sparse.
|
||||
Collecting all of it, or at least links to it, in one place sounds useful.
|
||||
|
||||
## accessing gitolite
|
||||
|
||||
The most common setup is based on ssh, where your admin asks you to send him
|
||||
your public key, and uses that to setup your access.
|
||||
|
||||
Your actual access is either a git command (like `git clone
|
||||
git@server:reponame`, and we won't be discussing these any more in this
|
||||
document), or an ssh command (like `ssh git@server info`).
|
||||
|
||||
Note that you do *not* get a shell on the server -- the whole point of
|
||||
gitolite is to prevent that!
|
||||
|
||||
## #info the info command
|
||||
|
||||
The only command that is *always* available to every user is the `info`
|
||||
command (run `ssh git@host info -h` for help), which tells you what version of
|
||||
gitolite and git are on the server, and what repositories you have access to.
|
||||
The list of repos is very useful if you have doubts about the spelling of some
|
||||
new repo that you know was setup.
|
||||
|
||||
## digression: two kinds of repos
|
||||
|
||||
Gitolite has two kinds of repos. Normal repos are specified by their full
|
||||
names in the config file. "Wildcard" repos are specified by a regex in the
|
||||
config file. Try the [`info` command][info] and see if it shows any lines
|
||||
that look like regex patterns, (with a "C" permission).
|
||||
|
||||
If you see any, it means you are allowed to create brand new repos whose names
|
||||
fit that pattern. When you create such a repo, your "ownership" of it (as far
|
||||
as gitolite is concerned) is *automatically* recorded by gitolite.
|
||||
|
||||
## other commands
|
||||
|
||||
### #perms set/get additional permissions for repos you created
|
||||
|
||||
The gitolite config may have several permissions lines for your repo, like so:
|
||||
|
||||
repo pub/CREATOR/..*
|
||||
RW+ = CREATOR
|
||||
RW = user1 user2
|
||||
R = user3
|
||||
|
||||
If that's all it had, you really can't do much. Any changes to access must be
|
||||
done by the administrator. (Note that "CREATOR" is a reserved word that gets
|
||||
expanded to your userid in some way, so the admin can literally add just the
|
||||
first two lines, and *every* authenticated user now has his own personal repo
|
||||
namespace, starting with `pub/<username>/`).
|
||||
|
||||
To give some flexibility to users, the admin could add rules like this:
|
||||
|
||||
RW = WRITERS
|
||||
R = READERS
|
||||
|
||||
(he could also add other roles but then he needs to read the documentation).
|
||||
|
||||
Once he does this, you can then use the `perms` command (run `ssh git@host
|
||||
perms -h` for help) to set permissions for other users by specifying which
|
||||
users are in the list of "READERS", and which in "WRITERS".
|
||||
|
||||
If you think of READERS and WRITERS as "roles", it will help. You can't
|
||||
change what access a role has, but you *can* say which users have that role.
|
||||
|
||||
**Note**: there isn't a way for you to see the actual rule set unless you're
|
||||
given read access to the special 'gitolite-admin' repo. Sorry. The idea is
|
||||
that your admin will tell you what "roles" he added into rules for your repos,
|
||||
and what permissions those roles have.
|
||||
|
||||
### #desc adding a description to repos you created
|
||||
|
||||
The `desc` command is extremely simple. Run `ssh git@host desc -h` for help.
|
||||
|
||||
## "site-local" commands
|
||||
|
||||
The main purpose of gitolite is to prevent you from getting a shell. But
|
||||
there are commands that you often need to run on the server (i.e., cannot be
|
||||
done by pushing something to a repo).
|
||||
|
||||
To enable this, gitolite allows the admin to setup scripts in a special
|
||||
directory that users can then run. Gitolite comes with a set of working
|
||||
scripts that your admin may install, or may use as a starting point for his
|
||||
own, if he chooses.
|
||||
|
||||
Think of these commands as equivalent to those in `COMMAND_DIR` in `man
|
||||
git-shell`.
|
||||
|
||||
You can get a list of available commands by running `ssh git@host help`.
|
||||
117
doc/users.mkd
117
doc/users.mkd
|
|
@ -1,96 +1,67 @@
|
|||
# what users (not admins) need to know about gitolite
|
||||
# adding and removing users
|
||||
|
||||
...written for the one guy in the world no one will think of as "just a normal
|
||||
user" ;-)
|
||||
Strictly speaking, gitolite doesn't know where users come from. If that
|
||||
surprises you, read [this][auth]. However, gitolite does help with ssh-based
|
||||
authentication, so here's some info on adding and removing users.
|
||||
|
||||
This document has some text, and a lot of links. Most of this info *is*
|
||||
available in the rest of the documentation, but it's scattered and sparse.
|
||||
Collecting all of it, or at least links to it, in one place sounds useful.
|
||||
> ----
|
||||
|
||||
## accessing gitolite
|
||||
> *WARNING: Do NOT add users directly on the server. Clone the
|
||||
> 'gitolite-admin' repo to your workstation, make changes to it, then add,
|
||||
> commit, and push. When the push hits the server, the server "acts" upon
|
||||
> your changes.*
|
||||
|
||||
The most common setup is based on ssh, where your admin asks you to send him
|
||||
your public key, and uses that to setup your access.
|
||||
> ----
|
||||
|
||||
Your actual access is either a git command (like `git clone
|
||||
git@server:reponame`, and we won't be discussing these any more in this
|
||||
document), or an ssh command (like `ssh git@server info`).
|
||||
All operations are in a clone of the gitolite-admin repo.
|
||||
|
||||
Note that you do *not* get a shell on the server -- the whole point of
|
||||
gitolite is to prevent that!
|
||||
To **add** a user, say Alice, obtain her public key (typically
|
||||
`$HOME/.ssh/id_rsa.pub` on her workstation), copy it to `keydir` with the user
|
||||
name as the basename (e.g., 'alice.pub' for user alice), then `git add
|
||||
keydir/alice.pub`. (All keys files must have names ending in ".pub", and must
|
||||
be in openssh's default format).
|
||||
|
||||
## #info the info command
|
||||
To **remove** a user, `git rm keydir/alice.pub`.
|
||||
|
||||
The only command that is *always* available to every user is the `info`
|
||||
command (run `ssh git@host info -h` for help), which tells you what version of
|
||||
gitolite and git are on the server, and what repositories you have access to.
|
||||
The list of repos is very useful if you have doubts about the spelling of some
|
||||
new repo that you know was setup.
|
||||
In both cases, you must commit and push. On receiving the push, gitolite will
|
||||
carry out the changes specified.
|
||||
|
||||
## digression: two kinds of repos
|
||||
The user name is simply the base name of the public key file name. So
|
||||
'alice.pub', 'foo/alice.pub' and 'bar/alice.pub', all resolve to user "alice".
|
||||
|
||||
Gitolite has two kinds of repos. Normal repos are specified by their full
|
||||
names in the config file. "Wildcard" repos are specified by a regex in the
|
||||
config file. Try the [`info` command][info] and see if it shows any lines
|
||||
that look like regex patterns, (with a "C" permission in addition to the "R"
|
||||
and the "W").
|
||||
## #multi-key multiple keys per user
|
||||
|
||||
If you see any, it means you are allowed to create brand new repos whose names
|
||||
fit that pattern. When you create such a repo, your "ownership" of it (as far
|
||||
as gitolite is concerned) is *automatically* recorded by gitolite.
|
||||
The simplest and most understandable is to put their keys in different
|
||||
subdirectories, (alice,pub, home/alice.pub, laptop/alice.pub, etc).
|
||||
|
||||
## other commands
|
||||
### old style multi-keys
|
||||
|
||||
### #perms set/get additional permissions for repos you created
|
||||
There is another way that involves creating key files like `alice@home.pub`
|
||||
and `alice@laptop.pub`, but there is a complication because gitolite also
|
||||
allows *full email addresses* as user names. (I.e., `sitaramc@gmail.com.pub`
|
||||
denotes the user called `sitaramc@gmail.com`).
|
||||
|
||||
The gitolite config may have several permissions lines for your repo, like so:
|
||||
This older method of enabling multi-keys was developed to deal with that. It
|
||||
will continue to work and be supported in *code*, simply because I prefer it.
|
||||
But I will not accept questions or doc patches for it, because it seems it is
|
||||
too difficult to understand for a lot of people. This table of sample pubkey
|
||||
filenames and the corresponding derived usernames is all you get:
|
||||
|
||||
repo pub/CREATOR/..*
|
||||
RW+ = CREATOR
|
||||
RW = user1 user2
|
||||
R = user3
|
||||
* plain username, no multikey
|
||||
|
||||
If that's all it had, you really can't do much. Any changes to access must be
|
||||
done by the administrator. (Note that "CREATOR" is a reserved word that gets
|
||||
expanded to your userid in some way, so the admin can literally add just the
|
||||
first two lines, and *every* authenticated user now has his own personal repo
|
||||
namespace, starting with `pub/<username>/`).
|
||||
sitaramc.pub sitaramc
|
||||
|
||||
To give some flexibility to users, the admin could add rules like this:
|
||||
* plain username, with multikeys
|
||||
|
||||
RW = WRITERS
|
||||
R = READERS
|
||||
sitaramc@laptop.pub sitaramc
|
||||
sitaramc@desktop.pub sitaramc
|
||||
|
||||
(he could also add other roles but then he needs to read the documentation).
|
||||
* email address as username, no multikey
|
||||
|
||||
Once he does this, you can then use the `perms` command (run `ssh git@host
|
||||
perms -h` for help) to set permissions for other users by specifying which
|
||||
users are in the list of "READERS", and which in "WRITERS".
|
||||
sitaramc@gmail.com.pub sitaramc@gmail.com
|
||||
|
||||
If you think of READERS and WRITERS as "roles", it will help. You can't
|
||||
change what access a role has, but you *can* say which users have that role.
|
||||
* email address as username, with multikeys
|
||||
|
||||
**Note**: there isn't a way for you to see the actual rule set unless you're
|
||||
given read access to the special 'gitolite-admin' repo. Sorry. The idea is
|
||||
that your admin will tell you what "roles" he added into rules for your repos,
|
||||
and what permissions those roles have.
|
||||
sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
|
||||
sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
|
||||
|
||||
### #desc adding a description to repos you created
|
||||
|
||||
The `desc` command is extremely simple. Run `ssh git@host desc -h` for help.
|
||||
|
||||
## "site-local" commands
|
||||
|
||||
The main purpose of gitolite is to prevent you from getting a shell. But
|
||||
there are commands that you often need to run on the server (i.e., cannot be
|
||||
done by pushing something to a repo).
|
||||
|
||||
To enable this, gitolite allows the admin to setup scripts in a special
|
||||
directory that users can then run. Gitolite comes with a set of working
|
||||
scripts that your admin may install, or may use as a starting point for his
|
||||
own, if he chooses.
|
||||
|
||||
Think of these commands as equivalent to those in `COMMAND_DIR` in `man
|
||||
git-shell`.
|
||||
|
||||
You can get a list of available commands by running `ssh git@host help`.
|
||||
|
|
|
|||
83
doc/vref.mkd
83
doc/vref.mkd
|
|
@ -1,5 +1,11 @@
|
|||
# virtual refs
|
||||
|
||||
**IMPORTANT**: fallthru is success in VREFs, unlike the normal refs. That
|
||||
won't make sense until you read further, but I had to put it up here for folks
|
||||
who stop reading halfway!
|
||||
|
||||
----
|
||||
|
||||
Here's an example to start you off.
|
||||
|
||||
repo r1
|
||||
|
|
@ -39,7 +45,7 @@ is therefore a *virtual* ref. This could be a property that git knows about,
|
|||
like in the example above, or comes from outside git like, say, the current
|
||||
time; see examples section later for some ideas.
|
||||
|
||||
## fallthru is success here
|
||||
## #vref-fallthru fallthru is success here
|
||||
|
||||
Notice that you didn't need to add an `RW+ VREF/...` rule for user `lead_dev`
|
||||
in our example. This section explains why.
|
||||
|
|
@ -53,7 +59,7 @@ ref involves calling an external program, many of these calls may be wasted.
|
|||
|
||||
There's another advantage to doing it this way: a VREF can choose to simply
|
||||
die if things look bad, and it will have the same effect, assuming you used
|
||||
the VREF only in [deny][] rules.
|
||||
the VREF only in "deny" rules.
|
||||
|
||||
This in turn means any existing update hook can be used as a VREF *as-is*, as
|
||||
long as it (a) prints nothing on success and (b) dies on failure. See the
|
||||
|
|
@ -169,26 +175,65 @@ first rule, it might pass back (to gitolite) a virtual ref saying
|
|||
|
||||
## VREFs shipped with gitolite
|
||||
|
||||
### #NAME restricting pushes by dir/file name
|
||||
|
||||
The "NAME" VREF allows you to restrict pushes by the names of dirs and files
|
||||
changed.
|
||||
|
||||
Here's an example. Say you don't want junior developers pushing changes to
|
||||
the Makefile, because it's quite complex:
|
||||
|
||||
repo foo
|
||||
RW+ = @senior_devs
|
||||
RW = @junior_devs
|
||||
|
||||
- VREF/NAME/Makefile = @junior_devs
|
||||
|
||||
When a senior dev pushes, the VREF is not invoked at all. But when a junior
|
||||
dev pushes, the VREF is invoked, and it returns a list of files changed **as
|
||||
refs**, looking like this:
|
||||
|
||||
VREF/NAME/file-1
|
||||
VREF/NAME/dir-2/file-3
|
||||
...etc...
|
||||
|
||||
Each of these refs is matched against the access rules. If one of them
|
||||
happens to be the Makefile, then the ref returned (VREF/NAME/Makefile) will
|
||||
match the deny rule and kill the push.
|
||||
|
||||
Another way to use this is when you know what is allowed instead of what is
|
||||
not allowed. Let's say the QA person is only allowed to touch a file called
|
||||
CHANGELOG and any files in a directory called ReleaseNotes:
|
||||
|
||||
repo foo
|
||||
RW+ = @senior_devs
|
||||
RW = @junior_devs
|
||||
RW+ = QA-guy
|
||||
|
||||
RW+ VREF/NAME/CHANGELOG = QA-guy
|
||||
RW+ VREF/NAME/ReleaseNotes/ = QA-guy
|
||||
- VREF/NAME/ = QA-guy
|
||||
|
||||
### number of new files
|
||||
|
||||
If a dev pushes more than 2 *new* files, the top commit needs to have a
|
||||
signed-off by line in its commit message. For example if he has 4 new files
|
||||
this text should be:
|
||||
The COUNT VREF is used like this:
|
||||
|
||||
4 new files signed-off by: <top commit author's email>
|
||||
- VREF/COUNT/9 = @junior-developers
|
||||
|
||||
The config entry for this is below (`NO_SIGNOFF` applies only to, and thus
|
||||
implies, `NEWFILES`):
|
||||
In response, if anyone in the user list pushes a commit series that
|
||||
changes more than 9 files, a vref of "VREF/COUNT/9" is returned. Gitolite
|
||||
uses that as a "ref" to match against all the rules, hits the same rule
|
||||
that invoked it, and denies the request.
|
||||
|
||||
RW+ VREF/COUNT/2/NO_SIGNOFF = sitaram
|
||||
- VREF/COUNT/2/NO_SIGNOFF = @all
|
||||
If the user did not push more than 9 files, the VREF code returns nothing,
|
||||
and nothing happens.
|
||||
|
||||
Notice how the refex in both cases is *exactly* the same. If you make it
|
||||
different (even change the number on my access line), things won't work.
|
||||
COUNT can take one more argument:
|
||||
|
||||
Junior devs can't push more than 10 new files, even with a signed-off by line:
|
||||
- VREF/COUNT/9/NEWFILES = @junior-developers
|
||||
|
||||
- VREF/COUNT/10/NEWFILES = @junior_devs
|
||||
This is the same as before, but have to be more than 9 *new* files not
|
||||
just changed files.
|
||||
|
||||
### advanced filetype detection
|
||||
|
||||
|
|
@ -220,6 +265,9 @@ have to change one subroutine in that script if you want to use it)
|
|||
|
||||
### catching duplicate pubkeys
|
||||
|
||||
This checks keydir/ for duplicate keys and aborts the push if it finds any.
|
||||
You should use this only on the gitolite-admin repo.
|
||||
|
||||
We covered this as a teaser example at the start.
|
||||
|
||||
## other ideas -- code welcome!
|
||||
|
|
@ -231,9 +279,10 @@ something like this (untested)
|
|||
|
||||
[ -z "$(git rev-list --first-parent --no-merges $2..$3)" ]
|
||||
|
||||
This can be implemented using `src/VREF/MERGE-CHECK` as a model.
|
||||
That script does what the 'in core' feature called [merge check][mergecheck]
|
||||
does, although the syntax to be used in conf/gitolite will be quite different.
|
||||
This can be implemented using `src/VREF/MERGE-CHECK` as a model. That script
|
||||
does what the 'M' qualifier does in access rules (see last part of
|
||||
[this][write-types]), although the syntax to be used in conf/gitolite will be
|
||||
quite different.
|
||||
|
||||
### other ideas for VREFs
|
||||
|
||||
|
|
|
|||
43
doc/why.mkd
43
doc/why.mkd
|
|
@ -1,4 +1,4 @@
|
|||
# Why is gitolite needed?
|
||||
# why might you need gitolite
|
||||
|
||||
Gitolite is separate from git, and needs to be installed and configured. So...
|
||||
why do we bother?
|
||||
|
|
@ -14,33 +14,34 @@ allow/disallow users access to repos.
|
|||
|
||||
But there are several disadvantages here:
|
||||
|
||||
* every user needs a userid and password on the server. This is usually a
|
||||
killer, especially in tightly controlled environments
|
||||
* adding/removing access rights involves complex `usermod -G ...` mumblings
|
||||
which most admins would rather not deal with
|
||||
* *viewing* (aka auditing) the current set of permissions requires running
|
||||
* Every user needs a userid and password on the server. This is usually a
|
||||
killer, especially in tightly controlled environments.
|
||||
* Adding/removing access rights involves complex `usermod -G ...` mumblings
|
||||
which most admins would rather not deal with.
|
||||
* *Viewing* (aka auditing) the current set of permissions requires running
|
||||
multiple commands to list directories and their permissions/ownerships,
|
||||
users and their group memberships, and then correlating all these manually
|
||||
* auditing historical permissions or permission changes is pretty much
|
||||
impossible without extraneous tools
|
||||
* errors or omissions in setting the permissions exactly can cause problems
|
||||
of either kind: false accepts or false rejects
|
||||
* without going into ACLs it is not possible to give some people read-only
|
||||
users and their group memberships, and then correlating all these
|
||||
manually.
|
||||
* Auditing historical permissions or permission changes is pretty much
|
||||
impossible without extraneous tools.
|
||||
* Errors or omissions in setting the permissions exactly can cause problems
|
||||
of either kind: false accepts or false rejects.
|
||||
* Without going into ACLs it is not possible to give some people read-only
|
||||
access while some others have read-write access to a repo (unless you make
|
||||
it world-readable). Group access just doesn't have enough granularity
|
||||
* it is absolutely impossible to restrict pushing by branch name or tag
|
||||
it world-readable). Group access just doesn't have enough granularity.
|
||||
* It is absolutely impossible to restrict pushing by branch name or tag
|
||||
name.
|
||||
|
||||
Gitolite does away with all this:
|
||||
|
||||
* it uses ssh magic to remove the need to give actual unix userids to
|
||||
developers
|
||||
* it uses a simple but powerful config file format to specify access rights
|
||||
* access control changes are affected by modifying this file, adding or
|
||||
removing user's public keys, and "compiling" the configuration
|
||||
* this also makes auditing trivial -- all the data is in one place, and
|
||||
* It uses ssh magic to remove the need to give actual unix userids to
|
||||
developers.
|
||||
* It uses a simple but powerful config file format to specify access rights.
|
||||
* Access control changes are affected by modifying this file, adding or
|
||||
removing user's public keys, and "compiling" the configuration.
|
||||
* This also makes auditing trivial -- all the data is in one place, and
|
||||
changes to the configuration are also logged, so you can audit them.
|
||||
* finally, the config file allows distinguishing between read-only and
|
||||
* Finally, the config file allows distinguishing between read-only and
|
||||
read-write access, not only at the repository level, but at the branch
|
||||
level within repositories.
|
||||
|
||||
|
|
|
|||
148
doc/wild.mkd
Normal file
148
doc/wild.mkd
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
# "wild" repos (user created repos)
|
||||
|
||||
## quick introduction
|
||||
|
||||
The wildrepos feature allows you to specify access control rules using regular
|
||||
expression patterns, so you can have many actual repos being served by a
|
||||
single set of rules in the config file. The regex pattern can also include
|
||||
the word `CREATOR` in it, allowing you to parametrise the name of the user
|
||||
creating the repo.
|
||||
|
||||
See the section on "repo patterns" later for additional information on what
|
||||
counts as a "wild" repo pattern and how it is matched.
|
||||
|
||||
## (admin) declaring wild repos in the conf file
|
||||
|
||||
Here's an example:
|
||||
|
||||
@prof = u1
|
||||
@TAs = u2 u3
|
||||
@students = u4 u5 u6
|
||||
|
||||
repo assignments/CREATOR/a[0-9][0-9]
|
||||
C = @students
|
||||
RW+ = CREATOR
|
||||
RW = WRITERS @TAs
|
||||
R = READERS @prof
|
||||
|
||||
Note the "C" permission. This is a standalone "C", which gives the named
|
||||
users the right to *create a repo*. <font color="gray">This is not to be
|
||||
confused with the "RWC" or its variants described elsewhere, which are about
|
||||
*branches*, not *repos*.</font>
|
||||
|
||||
## #create (user) creating a specific repo
|
||||
|
||||
For now, ignore the special usernames READERS and WRITERS, and just create a
|
||||
new repo, as user "u4" (a student):
|
||||
|
||||
$ git clone git@server:assignments/u4/a12
|
||||
Initialized empty Git repository in /home/sitaram/a12/.git/
|
||||
Initialized empty Git repository in /home/git/repositories/assignments/u4/a12.git/
|
||||
warning: You appear to have cloned an empty repository.
|
||||
|
||||
Notice the *two* empty repo inits, and the order in which they occur ;-)
|
||||
|
||||
## a slightly different example
|
||||
|
||||
Here's how the same example would look if you did not want the CREATOR's name
|
||||
to be part of the actual repo name.
|
||||
|
||||
repo assignments/a[0-9][0-9]
|
||||
C = @students
|
||||
RW+ = CREATOR
|
||||
RW = WRITERS @TAs
|
||||
R = READERS @prof
|
||||
|
||||
We haven't changed anything except the repo name pattern. This means that the
|
||||
first student that creates, say, `assignments/a12` becomes the owner.
|
||||
Mistakes (such as claiming a12 instead of a13) need to be rectified by an
|
||||
admin logging on to the back end, though it's not too difficult.
|
||||
|
||||
You could also repace the C line like this:
|
||||
|
||||
C = @TAs
|
||||
|
||||
and have a TA create the repos in advance.
|
||||
|
||||
## repo patterns
|
||||
|
||||
### pattern versus normal repo
|
||||
|
||||
Due to projects like `gtk+`, the `+` character is now considered a valid
|
||||
character for an *ordinary* repo. Therefore, a pattern like `foo/.+` does not
|
||||
look like a regex to gitolite. Use `foo/..*` if you want that.
|
||||
|
||||
Also, `..*` by itself is not considered a valid repo pattern. Try
|
||||
`[a-zA-Z0-9].*`.
|
||||
|
||||
### line-anchored regexes
|
||||
|
||||
A regex like
|
||||
|
||||
repo assignments/S[0-9]+/A[0-9]+
|
||||
|
||||
would match `assignments/S02/A37`. It will not match `assignments/S02/ABC`,
|
||||
or `assignments/S02/a37`, obviously.
|
||||
|
||||
But you may be surprised to find that it does not match even
|
||||
`assignments/S02/A37/B99`. This is because internally, gitolite
|
||||
*line-anchors* the given regex; so that regex actually becomes
|
||||
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
|
||||
metacharacters.
|
||||
|
||||
Side-note: contrast with refexes
|
||||
|
||||
> Just for interest, note that this is in contrast to the refexes for the >
|
||||
> normal "branch" permissions, as described in `doc/gitolite.conf.mkd` and
|
||||
> elsewhere. These "refexes" are only anchored at the start; a pattern like
|
||||
> `refs/heads/master` actually can match `refs/heads/master01/bar` as well,
|
||||
> even if no one will actually push such a branch! You can anchor both
|
||||
> sides if you really care, by using `master$` instead of `master`, but that
|
||||
> is *not* the default for refexes.
|
||||
|
||||
## roles
|
||||
|
||||
The tokens READERS and WRITERS are called "role" names. The access rules that
|
||||
the admin specifies say what permissions these roles have, but they don't say
|
||||
what users are in these roles.
|
||||
|
||||
That needs to be done by the creator of the repo, using the `perms` command.
|
||||
You can run `ssh git@host perms -h` for detailed help, but in brief, that
|
||||
command lets you give and take away roles to users.
|
||||
|
||||
## adding other roles
|
||||
|
||||
If you want to have more than just the 2 default roles, say something like:
|
||||
|
||||
repo foo/..*
|
||||
C = u1
|
||||
RW refs/tags/ = TESTERS
|
||||
- refs/tags/ = @all
|
||||
RW+ = WRITERS
|
||||
RW = INTERNS
|
||||
R = READERS
|
||||
RW+D = MANAGERS
|
||||
|
||||
You can add the new names to the ROLES hash in the [rc][] file. Be sure to
|
||||
run the 2 commands mentioned there after you have added the roles.
|
||||
file. The rc file documentation (`doc/gitolite.rc.mkd`) explains how.
|
||||
|
||||
#### #rolenamewarn **IMPORTANT WARNING ABOUT THIS FEATURE**
|
||||
|
||||
Please make sure that none of the role names conflict with any of the user
|
||||
names or group names in the system. For example, if you have a user called
|
||||
"foo" or a group called "@foo", make sure you do not include "foo" as a valid
|
||||
role in the ROLES hash.
|
||||
|
||||
You can keep things sane by using UPPERCASE names for roles, while keeping all
|
||||
your user and group names lowercase; then you don't have to worry about this
|
||||
problem.
|
||||
|
||||
## listing wild repos
|
||||
|
||||
In order to see what repositories were created from a wildcard, use the 'info'
|
||||
command. Try `ssh git@host info -h` to get help on the info command.
|
||||
|
||||
## deleting a wild repo
|
||||
|
||||
TBD
|
||||
Loading…
Reference in a new issue