Author: John Reese
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.
All repositories hosted by Gitosis have a “private” clone and push URL, which is used for authenticated, read/write access to the repository:
Public repositories have a separate clone URL that uses an unauthenticated connection to allow cloning the repository without any permissions check:
gitosis-admin repository maintains a special structure of information. When checked out, it looks like this:
gitosis-admin/ gitosis.conf keydir/ jreese.pub ....
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
This process assumes you have been granted admin access to Gitosis on the server.
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 email@example.com: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!
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
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 firstname.lastname@example.org:myplugin.git $ git push origin master
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
email@example.com:myplugin.git in order to be able to push changes back to the server.
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