-
Notifications
You must be signed in to change notification settings - Fork 999
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
40 changed files
with
2,532 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,34 @@ | ||
# 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
# gitolite "commands" | ||
|
||
Gitolite comes with several commands that users can run. Remote user run the | ||
commands by saying: | ||
|
||
ssh git@host command-name [args...] | ||
|
||
while on the server you can run | ||
|
||
gitolite command [args...] | ||
|
||
Very few commands are designed to be run both ways, but it can be done, by | ||
checking for the presence of env var `GL_USER`. | ||
|
||
You can get a **list of available commands** by using the `help` command. | ||
Naturally, a remote user will see only a subset of what the server user will | ||
see. | ||
|
||
You add commands to the "allowed from remote" list by adding its name (or | ||
uncommenting it if it's already added but commented out) to the COMMANDS hash | ||
in the [rc][] file. | ||
|
||
If you write your own commands, put them in src/commands. | ||
|
||
**Note that this is also the place that all triggered programs go**. In fact, | ||
all standalone programs related to gitolite go here. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
# 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
# customising gitolite | ||
|
||
Here are the ways you can customise gitolite on the server. | ||
|
||
First, learn about: | ||
|
||
* [git hooks][hooks] and [virtual refs][vref] | ||
|
||
* [commands][] for your [users][] to run own][dev-notes] | ||
|
||
* [triggers][] to be run by gitolite as various points in its execution | ||
|
||
* [syntactic sugar][sugar] to change the conf language for your convenience | ||
|
||
For all of the above: | ||
|
||
* [edit the rc file][rc] to enable optional features that are shipped in a | ||
disabled state | ||
|
||
* [write your own][dev-notes] | ||
|
||
(Note: "trigger" is the same concept as "hook", applied to gitolite; I just | ||
chose a different name to avoid constant ambiguity in documentation). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,116 @@ | ||
# notes for developers | ||
|
||
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. | ||
|
||
## environment variables | ||
|
||
In general, the following environment variables should always be available: | ||
|
||
GL_BINDIR | ||
GL_REPO_BASE | ||
GL_ADMIN_BASE | ||
|
||
Commands invoked by a remote client will also have `GL_USER` set. Hooks will | ||
have `GL_REPO` also set. | ||
|
||
## 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 | ||
more info. | ||
|
||
* `gitolite access` to check access rights given repo, user, type of access | ||
(R, W, ...) and refname (optional). Example use: src/commands/desc | ||
|
||
* `gitolite creator` to get/check the creator of a repo. Example use: | ||
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 | ||
actual `repo.git/config` file or using the `git config` command). Example | ||
use: none yet | ||
|
||
* `gitolite query-rc` to check the value of an RC variable. Example use: | ||
src/commands/desc. | ||
|
||
In addition, you can also look at the comments in src/Gitolite/Easy.pm (the | ||
perl API module) for ideas. | ||
|
||
### the perl API | ||
|
||
...is implemented by Gitolite::Easy; see src/Gitolite/Easy.pm. This is a work | ||
in progress; for example it does not yet have the equivalent of `gitolite | ||
git-config`. I'll add it when I or someone else needs it. | ||
|
||
## your own 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 | ||
|
||
If you want to add additional `update` hook functionality, do this: | ||
|
||
* write and test your update hook separately from gitolite | ||
|
||
* now add the code to src/VREF. Let's say it is called "foo". | ||
|
||
* to call your new update hook to all accesses for all repos, add this to | ||
the end of your conf file: | ||
|
||
repo @all | ||
- VREF/foo = @all | ||
|
||
As you probably guessed, you can now make your additional update hooks more | ||
selective, applying them only to some repos / users / combinations. | ||
|
||
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 | ||
|
||
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 | ||
by a remote user by adding them to the "COMMANDS" hash of the [rc][] file. | ||
|
||
Commands are standalone programs, in any language you like. They simply | ||
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 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. | ||
|
||
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" | ||
|
||
Syntactic sugar helpers are NOT complete, standalone, programs. They must | ||
include a perl sub called `sugar_script` that takes in a listref, and returns | ||
a listref. The listrefs point to a list that contains the entire conf file | ||
(with all [include][] processing already done). You create a new list with | ||
contents modified as you like and return a ref to it. | ||
|
||
There are a couple of examples in src/syntactic-sugar. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
## #dev-status g3 development status | ||
|
||
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 | ||
* 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) | ||
|
||
Help needed: | ||
|
||
* I'd like distro packagers to play with it and help with migration advice | ||
for distro-upgrades | ||
* [rsync][pw2], 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 | ||
anyway!): | ||
|
||
* mob branches | ||
* password access | ||
* specific ADCs -- there are too many for me to bother without applying | ||
Pareto somewhere, so I choose to not do any and wait for people to ask :-) | ||
|
||
Done: | ||
|
||
* core code | ||
* test suite | ||
* some documentation | ||
* distro packaging instructions | ||
* migration advice for common cases |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,89 @@ | ||
# authentication versus authorisation | ||
|
||
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]. | ||
|
||
Here is a fundamental point: <font color="red">**Gitolite does not do | ||
authentication. It only does authorisation**.</font> | ||
|
||
So first, let's loosely define these words: | ||
|
||
> **Authentication** is the process of verifying that you are who you claim | ||
> to be. An authentication system will establish that I am the user | ||
> "sitaram" on my work system. The one behind gmail will similarly | ||
> establish that I am "sitaramc". And so on... | ||
> **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 | ||
know that gitolite is meant to be invoked as: | ||
|
||
/full/path/to/gl-auth-command 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! | ||
|
||
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**. | ||
|
||
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. | ||
|
||
## 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.) | ||
|
||
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 | ||
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 | ||
|
||
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 | ||
authentication was done. Which in turn means you can use whatever | ||
authentication scheme you want. | ||
|
||
It also expects the `SSH_ORIGINAL_COMMAND` environment variable to contain the | ||
full command (typically starting with git-receive-pack or git-upload-pack) | ||
that the client sent. Also, when using [smart http][http], things are somewhat | ||
different: gitolite uses certain environment variables that it expects httpd | ||
to have set up. Even the user name comes from the `REMOTE_USER` environment | ||
variable instead of as a command line argument in this case. | ||
|
||
However, it has to be an authentication system that is compatible with sshd or | ||
httpd in some form. Why? Because the git *client* accessing the server only | ||
knows those 2 protocols to "speak git". (Well, the `git://` protocol is | ||
unauthenticated, and `file://` doesn't really apply to this discussion, so | ||
we're ignoring those). | ||
|
||
For example, let's say you have an LDAP-based authentication system somewhere. | ||
It is possible to make apache use that to authenticate users, so when a user | ||
accesses a git url using `http://sitaram:password@git.example.com/repo`, it is | ||
LDAP that does the actual authentication. [I wouldn't know how to do it but I | ||
know it is possible. Patches to this doc explaining how are welcome!] | ||
|
||
There are also ssh daemons that use LDAP to store the authorised keys (instead | ||
of putting them all in `~/.ssh/authorized_keys`). The clients will still need | ||
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. | ||
|
Oops, something went wrong.