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

MASSIVE set of changes to documents!

Browse source 
I got tired of being told "TL;DR".  Now the online versions of most
documents fit on a page or two, or at least most of them do.  The rest
has been split out (and you can see the links to the split out sections
right where the text is in the raw Markdown).

This is much more pleasant to read, and I've improved the linking so
it's much less effort for me to keep the links correct.
This commit is contained in:
Sitaram Chamarty 2011-11-01 10:33:20 +05:30
parent 3f87430c5a
commit 6e29365316
45 changed files with 1194 additions and 2706 deletions
Download patch file Download diff file Expand all files Collapse all files

13
contrib/adc/README.mkd → contrib/adc/README-adc.mkd
View file

@ -1,4 +1,4 @@
## brief descriptions of the shipped ADCs (admin-defined commands)
# F=shipped_ADCs brief descriptions of the shipped ADCs (admin-defined commands)
(...with pointers to further information where needed)
@ -8,19 +8,14 @@
or other admin chores); details [here][able]. This ADC is meant only for
admins.
[able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily
**delete-branch**: allow someone to delete a branch that they themselves
created. (i.e., when the user had RWC, but not RWCD, permissions). Details on
this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd].
[dbsha]: https://github.com/sitaramc/gitolite/commit/89b68bf5ca99508caaa768c60ce910d7e0a29ccf
[rwcd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_creating_and_deleting_branches
**fork**: Think of it as a server-side clone; details [here][fork].
[fork]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_fork
**get-rights-and-owner.in-perl**: Most of the ADCs are in shell, so this is a
sample of how to write an ADC in perl.
@ -36,14 +31,10 @@ itself. This ADC displays site-local help, if the site admin enabled it.
**hub**: allow "pull requests" a la github; details [here][hub].
[hub]: http://sitaramc.github.com/gitolite/contrib/adc/hub.html
**rm**, **lock**, and **unlock**:<br>
**trash**, **list-trash**, and **restore**:
> two families of repo deletion commands; details [here][rddoc]
[rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
> two families of repo deletion commands; details [here][wild_repodel]
**sudo**: allow admin to run ADCs on behalf of a user. Useful in support
situations I guess. Details in source.

40
contrib/adc/hub.mkd
View file

@ -1,18 +1,6 @@
## the 'hub' ADC
# F=hub the 'hub' ADC
In this document:
* <a href="#_a_home_grown_hub_for_git_repos">a home grown 'hub' for git repos</a>
* <a href="#_general_syntax">general syntax</a>
* <a href="#_Bob_s_commands">Bob's commands</a>
* <a href="#_Alice_s_just_looking_commands">Alice's "just looking" commands</a>
* <a href="#_Alice_s_action_commands">Alice's "action" commands</a>
* <a href="#_what_next_">what next?</a>
* <a href="#_note_to_the_admin_configuration_variables">note to the admin: configuration variables</a>
<a name="_a_home_grown_hub_for_git_repos"></a>
### a home grown 'hub' for git repos
## a home grown 'hub' for git repos
This ADC (admin-defined command) helps collaboration among repos. The name is
in honor of github, which is the primary host for gitolite itself.
@ -51,17 +39,13 @@ do a normal `git fetch [origin]` to get it to her workstation. This has the
added advantage that other people, who may be watching her repo but not Bob's,
now get to see what Bob sent her and send comments etc.
<a name="_general_syntax"></a>
### general syntax
## general syntax
The general syntax is
ssh git@server hub <hub-command> <args>
<a name="_Bob_s_commands"></a>
#### Bob's commands
### Bob's commands
The following commands do not cause a fetch, and should be quite fast:
@ -92,9 +76,7 @@ The following commands do not cause a fetch, and should be quite fast:
ssh git@server hub request-status child [parent] request-number
<a name="_Alice_s_just_looking_commands"></a>
#### Alice's "just looking" commands
### Alice's "just looking" commands
* Alice lists requests waiting for her to check and possibly pull into
parent. For each waiting pull request, she will see a serial number, the
@ -140,9 +122,7 @@ The following commands do not cause a fetch, and should be quite fast:
to ADCs, you probably can't do things like `pu^` or `master~3`, and have
to use SHAs instead.
<a name="_Alice_s_action_commands"></a>
#### Alice's "action" commands
### Alice's "action" commands
* Alice doesn't like what she sees and decides to reject it. This command
expects some text on STDIN as the rejection message:
@ -179,9 +159,7 @@ The following commands do not cause a fetch, and should be quite fast:
Notice the sequence of Alice's action commands: it's either 'reject', or a
'fetch' then 'accept'.
<a name="_what_next_"></a>
### what next?
## what next?
At this point, you're done with the `hub` ADC. However, all this is on the
bare `parent.git` on the server, and nothing has hit Alice's workstation yet!
@ -195,9 +173,7 @@ Finally, note that Alice does not actually need to use the `fetch` subcommand.
She can do the traditional thing and fetch Bob's repo/branch directly to her
*workstation*.
<a name="_note_to_the_admin_configuration_variables"></a>
### note to the admin: configuration variables
## note to the admin: configuration variables
There are 2 configuration variables. `BASE_FETCH_URL` should be set to a
simple "read" URL (so it doesn't even have to be ssh) that almost anyone using

9
contrib/adc/repo-deletion.mkd
View file

@ -1,11 +1,8 @@
## deleting repos safely
# F=wild_repodel deleting repos safely
**NOTE**: this page is about deleting [user-created repos][wcr]. It is
**NOTE**: this page is about deleting [user-created repos][wild]. It is
**not** about deleting "normal" repos (the kind that are specified in the
gitolite.conf file itself) -- to delete those read [here][dnr].
[wcr]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
[dnr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_deleting_a_repo
gitolite.conf file itself) -- to delete those read [here][repodel].
(see [this thread][thr] on the gitolite mailing list)

85
contrib/adc/sskm.mkd
View file

@ -1,38 +1,16 @@
## changing keys -- self service key management
# F=sskm changing keys -- self service key management
Follow this guide to add keys to or remove keys from your account. Note that you cannot use this method to add your *first* key to the account; you must still email your initial key to your admin.
The key management is done using an ADC (admin-defined command) called `sskm`.
In this document:
* <a href="#_Important_">Important!</a>
* <a href="#_Key_fingerprints">Key fingerprints</a>
* <a href="#_Active_keys">Active keys</a>
* <a href="#_Selecting_which_key_to_use">Selecting which key to use</a>
* <a href="#_Public_vs_private_keys">Public vs. private keys</a>
* <a href="#_Listing_your_existing_keys">Listing your existing keys</a>
* <a href="#_Adding_or_Replacing_a_key">Adding or Replacing a key</a>
* <a href="#_Step_1_Adding_the_Key">Step 1: Adding the Key</a>
* <a href="#_Step_2_Confirming_the_addition">Step 2: Confirming the addition</a>
* <a href="#_Optional_Undoing_a_mistaken_add_before_confirmation_">Optional: Undoing a mistaken add (before confirmation)</a>
* <a href="#_Removing_a_key">Removing a key</a>
* <a href="#_Step_1_Mark_the_key_for_deletion">Step 1: Mark the key for deletion</a>
* <a href="#_Step_2_Confirming_the_deletion">Step 2: Confirming the deletion</a>
* <a href="#_Optional_Undoing_a_mistaken_delete_before_confirmation_">Optional: Undoing a mistaken delete (before confirmation)</a>
* <a href="#_important_notes_for_the_admin">important notes for the admin</a>
----
<a name="_Important_"></a>
### Important!
## Important!
There are a few things that you should know before using the key management system. Please do not ignore this section!
<a name="_Key_fingerprints"></a>
#### Key fingerprints
### Key fingerprints
Keys are identified in some of these subcommands by their fingerprints. To see the fingerprint for a public key on your computer, use the following syntax:
@ -43,18 +21,13 @@ You'll get output like:
jeff@baklava ~ $ ssh-keygen -l -f .ssh/jeffskey.pub
2048 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 .ssh/jeffskey.pub (RSA)
<a name="_Active_keys"></a>
#### Active keys
### Active keys
Any keys that you can use to interact with the system are active keys. (Inactive keys are keys that are, for instance, scheduled to be added or removed.) Keys are identified with their `keyid`; see the section below on listing keys.
If you have no current active keys, you will be locked out of the system (in which case email your admin for help). Therefore, be sure that you are never removing your only active key!
<a name="_Selecting_which_key_to_use"></a>
#### Selecting which key to use
### Selecting which key to use
Although you can identify yourself to the Gitolite system with any of your active keys on the server, at times it is necessary to specifically pick which key you are identifying with. To pick the key to use, pass the `-i` flag into `ssh`:
@ -75,15 +48,11 @@ disable the agent, using one of these commands:
* If using `keychain`, run `keychain --clear` to remove identities
* Unset the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` variables in the current shell
<a name="_Public_vs_private_keys"></a>
#### Public vs. private keys
### Public vs. private keys
In this guide, all keys are using their full suffix. In other words, if you see a `.pub` at the end of a key, it's the public key; if you don't, it's the private key. For instance, when using the `-i` flag with `ssh`, you are specifying private keys to use. When you are submitting a key for addition to the system, you are using the public key.
<a name="_Listing_your_existing_keys"></a>
### Listing your existing keys
## Listing your existing keys
To see a list of your existing keys, use the `list` argument to `sskm`:
@ -103,13 +72,9 @@ use any keyid you wish when adding keys (like `@home`, `@laptop`, ...); the
only rules are that it must start with the `@` character and after that
contain only digits, letters, or underscores.
<a name="_Adding_or_Replacing_a_key"></a>
## Adding or Replacing a key
### Adding or Replacing a key
<a name="_Step_1_Adding_the_Key"></a>
#### Step 1: Adding the Key
### Step 1: Adding the Key
Adding and replacing a key is the same process. What matters is the `keyid`. When adding a new key, use a new `keyid`; when replacing a key, pass in the `keyid` of the key you want to replace, as found by using the `list` subcommand. Pretty simple!
@ -132,9 +97,7 @@ If you now run the `list` command you'll see that it's scheduled for addition:
== keys marked for addition/replacement ==
1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
<a name="_Step_2_Confirming_the_addition"></a>
#### Step 2: Confirming the addition
### Step 2: Confirming the addition
Gitolite uses Git internally to store the keys. Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-add` subcommand to do this, *but*: to verify that you truly have ownership of the corresponding private key, you *must* use the key you are adding itself to do the confirmation! (Inconvenient like most security, but very necessary from a security perspective.) This is where using the `-i` flag of `ssh` comes in handy:
@ -152,9 +115,7 @@ Listing keys again shows that all four keys are now active:
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
<a name="_Optional_Undoing_a_mistaken_add_before_confirmation_"></a>
#### Optional: Undoing a mistaken add (before confirmation)
### Optional: Undoing a mistaken add (before confirmation)
Another advantage of Gitolite using Git internally is that that if we mistakenly add the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to remove into the `undo-add` subcommand:
@ -171,13 +132,9 @@ Listing the keys shows that that new key has been removed:
2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
<a name="_Removing_a_key"></a>
## Removing a key
### Removing a key
<a name="_Step_1_Mark_the_key_for_deletion"></a>
#### Step 1: Mark the key for deletion
### Step 1: Mark the key for deletion
Deleting a key works very similarly to adding a key, with `del` substituted for `add`.
@ -211,9 +168,7 @@ Listing the keys now shows that it is marked for deletion:
== keys marked for deletion ==
1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
<a name="_Step_2_Confirming_the_deletion"></a>
#### Step 2: Confirming the deletion
### Step 2: Confirming the deletion
Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-del` subcommand to do this, *but*: unlike the `confirm-add` subcommand, you *must* use a *different* key than the key you are deleting to do the confirmation! This prevents you from accidentally locking yourself out of the system by removing all active keys:
@ -230,9 +185,7 @@ Listing keys again shows that the fourth key has been removed:
2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
<a name="_Optional_Undoing_a_mistaken_delete_before_confirmation_"></a>
#### Optional: Undoing a mistaken delete (before confirmation)
### Optional: Undoing a mistaken delete (before confirmation)
Another advantage of Gitolite using Git internally is that that if we mistakenly delete the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to keep into the `undo-del` subcommand. Note that this operation *must* be performed using the private key that corresponds to the key you are trying to keep! (Security reasons, similar to the reason that you must confirm an addition this way; it prevents anyone from undoing a deletion, and therefore keeping in the system, a key that they cannot prove (by having the corresponding private key) should stay in the system):
@ -260,9 +213,7 @@ Listing the keys shows that that new key is now marked active again:
----
<a name="_important_notes_for_the_admin"></a>
### important notes for the admin
## important notes for the admin
These are the things that can break if you enable this ADC for your users:
@ -279,10 +230,8 @@ These are the things that can break if you enable this ADC for your users:
So, if you have the same *filename* in different subdirectories of
`keydir`, you can't use this tool.
* keys placed in specific folders (perhaps to do [this][optak], or for
* keys placed in specific folders (perhaps to do [this][authkeyopt], or for
whatever other reasons), will probably not stay in those folders if this
ADC is used. Even a key delete, followed by undoing the delete, will
cause the key to effectively move to the root of the key store (i.e., the
`keydir` directory in the gitolite-admin repo).
[optak]: http://sitaramc.github.com/gitolite/doc/big-config.html#_optimising_the_authkeys_file