Table of Contents
Managing Gitosis Repositories
Author: John Reese
Concepts
Gitosis stores repositories in the 'git' user's home directory. In the case of git.mantisbt.org, this path is /srv/git
. Configuration of the hosted repositories is defined in a special repository gitosis-admin.git
, which contains a single configuration file and a directory of users' SSH keys.
Gitosis does its magic via the post-update
hook in the gitosis-admin
repository; in other words, every time you push changes to the special repository, it automatically updates all the appropriate settings, files, etc on the server to match the new configuration.
Clone and Push URL's
All repositories hosted by Gitosis have a “private” clone and push URL, which is used for authenticated, read/write access to the repository:
git@mantisbt.org:<repository>.git
Public repositories have a separate clone URL that uses an unauthenticated connection to allow cloning the repository without any permissions check:
git://mantisbt.org/<repository>.git
Repository Layout
The gitosis-admin
repository maintains a special structure of information. When checked out, it looks like this:
gitosis-admin/ gitosis.conf keydir/ jreese.pub ....
The file gitosis.conf
contains configuration information for all the repositories managed by Gitosis, including the gitosis-admin
repo. It defines repositories and groups of users, and associated read/write privileges.
Because Git/Gitosis relies on SSH access for users to push changes to repositories, users are identified by their public SSH keys. The keydir/
directory contains all users' public keys in the filename format of <username>.pub
.
Repository Management
This process assumes you have been granted admin access to Gitosis on the server.
General Process
Start by cloning the gitosis-admin
repository. Naturally, you only need to do this once; any later changes to the repository can be handled using the same clone.
$ git clone git@mantisbt.org:gitosis-admin.git
Now that you have a successful clone, you can make your changes. Once you're done making changes, commit your changes, and push them back to the server.
$ git commit -a -m "<What you just did>" $ git push
Gitosis will then handle updating all the repositories appropriately. You're done!
Adding a New Repository
For this section, we'll assume you want to create a new repository named myplugin
, and give write access to the repository owner jsmith
and the core developer group core
. You will want to replace the repository, user, or group names as appropriate.
By default, all new repositories remain private, meaning that only the users you grant explicit read/write access through Gitosis will be able to interact with it. We'll cover how to make a private repository public later.
$ cd gitosis-admin
Edit gitosis.conf
and add a section to the end of the file with the following contents:
[repo myplugin] description = A plugin for the Mantis Bug Tracker. owner = John Smith [group myplugin] writable = myplugin members = jsmith @core
Notice that both the repo and the new group share the same name so that their relation is obvious when looking at the file. Also of note is that the core
group is prefixed with an @
in the members assignment to reference a [group]
section elsewhere in the file.
If the user jsmith
has not been previously added to Gitosis, add his public SSH key to the appropriate file:
$ cat > keydir/jsmith.pub ... ^D
Now you need to add and commit your changes to the repository, and then push your commit back to the server:
$ git add gitosis.conf keydir/jsmith.pub $ git commit -m "Added 'myplugin' repository and 'jsmith' user." $ git pull --rebase # make sure we have the latest updates from the server $ git push
Congratulations! Your new repository is now configured through Gitosis. Note that you will get an error that the repository doesn't exist. Your next step is to push an existing Git checkout/clone to the new repository URL:
$ cd /path/to/myplugin $ git remote rm origin $ git remote add origin git@mantisbt.org:myplugin.git $ git push origin master
You're done!
Making a Repository Public
We'll assume the same repository name of myplugin
, and that we want the repository to be publicly available without authentication, and viewable on the web via gitweb. You'll need to have root access on the server to perform these steps.
First, we need to open up permissions on the repository directory so that all users have read and execute permissions:
# sudo chmod 755 ~git/repositories/myplugin.git
Next we need to symlink to the repository from a location where git-daemon and gitweb are both looking for shared repos:
# sudo ln -s ~git/repositories/myplugin.git /var/cache/git/
Congratulations! You can view the repository with gitweb at a URL similar to http://git.mantisbt.org/?p=myplugin.git, and users can clone the repository from the URL git:mantisbt.org/myplugin.git
Remember: git: only provides read access to the repository. Developers will still need to clone from git@mantisbt.org:myplugin.git
in order to be able to push changes back to the server.
References
[1] http://scie.nti.st/2007/11/14/hosting-git-repositories-the-easy-and-secure-way
[0] Gitosis example.conf
(Snipped unappliccable parts)
# this config file tries to show a bit of everything, most real life # configurations really only need a "group" section with "members" and # "writable" [gitosis] [group quux] members = jdoe wsmith @anothergroup writable = foo bar baz/thud readonly = xyzzy ## You can use groups just to avoid listing users multiple times. Note ## no writable= or readonly= lines. [group anothergroup] members = alice bill ## You can play fancy tricks by making some repositories appear with ## different names in different contexts. Not really supported ## everywhere (e.g. gitweb) and can be confusing -- experts only. map writable visiblename1 = actualname1 map readonly visiblename2 = actualname2 [repo foo] ## Oneline description of the project, mostly for gitweb. description = blah blah ## Owner of this repository. Used in gitweb list of projects. owner = John Doe