219 lines
9.2 KiB
Markdown
219 lines
9.2 KiB
Markdown
# administering and running gitolite
|
|
|
|
*Note*: some of the paths in this document use variable names. Just refer to
|
|
`~/.gitolite.rc` for the correct values for *your* installation.
|
|
|
|
In this document:
|
|
|
|
* <a href="#please_read_this_first">please read this first</a>
|
|
* <a href="#adding_users_and_repos">adding users and repos</a>
|
|
* <a href="#other_features">other features</a>
|
|
* <a href="#moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
|
|
* <a href="#specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
|
|
* <a href="#custom_hooks">custom hooks</a>
|
|
* <a href="#hook_chaining">hook chaining</a>
|
|
* <a href="#environment_variables_available_to_hooks">environment variables available to hooks</a>
|
|
* <a href="#custom_git_config">custom git config</a>
|
|
|
|
----
|
|
|
|
<a name="please_read_this_first"></a>
|
|
|
|
### please read this first
|
|
|
|
* ***do NOT add new repos manually***, unless you know how to add the
|
|
required hook as well. Without the hook, branch-level access control will
|
|
not work for that repo, which sorta defeats the idea of using gitolite :-)
|
|
|
|
* most normal (day-to-day) gitolite admin work is done by cloning the
|
|
gitolite-admin repo from the server to your workstation, making changes to
|
|
the clone, and pushing those changes back. The installation steps in
|
|
[doc/0-INSTALL.mkd][doc0] include the steps to do this clone if needed.
|
|
|
|
Once you've cloned it, you're ready to add users and repos.
|
|
|
|
<a name="adding_users_and_repos"></a>
|
|
|
|
### adding users and repos
|
|
|
|
* ask each user who will get access to send you a public key. See other
|
|
sources (for example [here][genpub]) for how to do this
|
|
|
|
* rename each public key according to the user's name, with a `.pub`
|
|
extension, like `sitaram.pub` or `john-smith.pub`. You can also use
|
|
periods and underscores
|
|
|
|
* copy all these `*.pub` files to `keydir` in your gitolite-admin repo
|
|
clone. You can also organise them into various subdirectories of `keydir`
|
|
if you wish, since the entire tree is searched.
|
|
|
|
* edit the config file (`conf/gitolite.conf` in your admin repo clone). See
|
|
`conf/example.conf` in the gitolite source for details on what goes in
|
|
that file, syntax, etc. Just add new repos as needed, and add new users
|
|
and give them permissions as required. The users names should be exactly
|
|
the same as their keyfile names, but without the `.pub` extension
|
|
|
|
* when done, commit your changes and push. Any new repos you specified will
|
|
automatically be created (empty, but clonable) and users' access will be
|
|
updated as needed.
|
|
|
|
<a name="other_features"></a>
|
|
|
|
### other features
|
|
|
|
<a name="moving_pre_existing_repos_into_gitolite"></a>
|
|
|
|
#### moving pre-existing repos into gitolite
|
|
|
|
One simple way to add a pre-existing repo to gitolite is to let gitolite
|
|
create it as a brand new repo as in the previous section, then do the
|
|
following:
|
|
|
|
cd your-copy-of-the-repo
|
|
# make sure all the branches are correct and no extra stuff, "temp"
|
|
# branches, etc., are present
|
|
git push --all git@server:reponame
|
|
git push --tags git@server:reponame
|
|
|
|
(You could also use "git push --mirror" instead of separately doing branches
|
|
and tags, but that will carry across *your* remote refs also, and typically
|
|
you may not want that. Anyway please do a `git ls-remote git@server:repo` to
|
|
make sure all the stuff you want went through, and is named correctly).
|
|
|
|
All this is actually very simple and easily done. However, if you have many
|
|
existing repos to add, this can be time-consuming and error-prone. Here's how
|
|
to take a bunch of existing repos and add them to gitolite:
|
|
|
|
* make sure they're *bare* repos ;-)
|
|
|
|
* log on to the server and copy the repos to `$REPO_BASE` (which defaults to
|
|
`~/repositories`), making sure that the directory names end in ".git".
|
|
|
|
* back on your workstation, add each repo (without the `.git` suffix) to
|
|
`conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit,
|
|
push.
|
|
|
|
<a name="specifying_gitweb_and_daemon_access"></a>
|
|
|
|
#### specifying gitweb and daemon access
|
|
|
|
This is a feature that I personally do not use (corporate environments don't
|
|
like unauthenticated access of any kind to any repo!), but someone wanted it,
|
|
so here goes.
|
|
|
|
To make a repo or repo group accessible via "git daemon", just give read
|
|
permission to the special user "daemon". See the [faq, tips, etc][ss]
|
|
document for easy ways to specify access for multiple repositories.
|
|
|
|
[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd
|
|
|
|
There's a special user called "gitweb" also, which works the same way.
|
|
However, setting a description for the project also enables gitweb permissions
|
|
so you may as well use that method and kill two birds with one stone, like so:
|
|
|
|
gitolite = "fast, secure, access control for git in a corporate environment"
|
|
|
|
You can also specify an owner for gitweb to show, if you like:
|
|
|
|
gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"
|
|
|
|
Note that gitolite does **not** install or configure gitweb/daemon -- that is
|
|
a one-time setup you must do separately. All this does is:
|
|
|
|
* for daemon, create the file `git-daemon-export-ok` in the repository
|
|
* for gitweb, add the repo (plus owner name, if given) to the list of
|
|
projects to be served by gitweb (see the config file variable
|
|
`$PROJECTS_LIST`, which should have the same value you specified for
|
|
`$projects_list` when setting up gitweb)
|
|
* put the description, if given, in `$repo/description`
|
|
|
|
The "compile" script will keep these files consistent with the config settings
|
|
-- this includes removing such settings/files if you remove "read" permissions
|
|
for the special usernames or remove the description line.
|
|
|
|
<a name="custom_hooks"></a>
|
|
|
|
#### custom hooks
|
|
|
|
You can supply your own, custom, hook scripts if you wish. Just put a
|
|
**tested** hook script in `hooks/common` of your gitolite clone (as
|
|
distributed, there are only two files there). For each file in that
|
|
directory, a symlink pointing to it will be placed in the `hooks/`
|
|
subdirectory of every *new* repo created.
|
|
|
|
If you added any new hooks and wish to propagate them to *existing* repos as
|
|
well, just run gl-easy-install (or gl-setup, if you installed directly on the
|
|
server) once.
|
|
|
|
**VERY IMPORTANT SECURITY NOTE: the `update` hook in `hooks/common` is what
|
|
implements all the branch-level permissions in gitolite. If you fiddle with
|
|
the hooks directory, please make sure you do not mess with this file
|
|
accidentally, or all your fancy per-branch permissions will stop working.**
|
|
|
|
<a name="hook_chaining"></a>
|
|
|
|
#### hook chaining
|
|
|
|
Gitolite basically takes over the update hook for all repos, but some setups
|
|
really need the update hook functionality for their own purposes too. In
|
|
order to allow this, Gitolite now exec's a hook called `update.secondary` when
|
|
it's own "update" hook is done and everything is ready to go.
|
|
|
|
You can create this `update.secondary` hook manually on selected repos on the
|
|
server, or use the mechanism in the previous section to make gitolite put it
|
|
on *all* your repos.
|
|
|
|
Similarly, gitolite also takes over the post-update hook for the special
|
|
"gitolite-admin" repo. This hook will also chain to a `post-update.secondary`
|
|
if such a hook exists. People wishing to do exotic things on the server side
|
|
when the admin repo is pushed should see doc/shell-games.notes for how to
|
|
exploit this :-)
|
|
|
|
Finally, these names (`update.secondary` and `post-update.secondary`) are
|
|
merely the defaults. You can change them to anything you want; look in
|
|
conf/example.gitolite.rc for details.
|
|
|
|
<a name="environment_variables_available_to_hooks"></a>
|
|
|
|
#### environment variables available to hooks
|
|
|
|
The following environment variables are set, and may be useful for any custom
|
|
processing you wish to do in your hook code:
|
|
|
|
* `GL_USER` -- the user doing the push
|
|
* `GL_REPO` -- the reponame
|
|
* `GL_REPO_BASE_ABS` -- the absolute base path where all the repos are kept
|
|
|
|
The following variables are also set, but are generally less useful:
|
|
|
|
* `GL_BINDIR` -- where all the binaries live
|
|
* `GL_ADMINDIR` -- common directory for many gitolite things
|
|
|
|
<a name="custom_git_config"></a>
|
|
|
|
#### custom git config
|
|
|
|
The custom hooks feature is a blunt instrument -- all repos get the hook you
|
|
specified and will run it. In order to make it a little more fine-grained,
|
|
you could set your hooks to only work if a certain "gitconfig" variable was
|
|
set. Which means we now need a way to specify "git config" settings on a per
|
|
repository basis.
|
|
|
|
Thanks to Teemu (teemu dot matilainen at iki dot fi), gitolite now does this
|
|
very easily. For security reasons, this can only be done from the master
|
|
config file (i.e., if you're using delegation, the delegated admins cannot
|
|
specify git config settings).
|
|
|
|
Please see `conf/example.conf` for syntax. Note that this only supports the
|
|
basic forms of the "git config" command:
|
|
|
|
git config section.key value # value may be an empty string
|
|
git config --unset-all section.key
|
|
|
|
It does not (currently) support other options like `--add`, the `value_regex`,
|
|
etc.
|
|
|
|
[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
|
|
[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
|
|
|