User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:gitosis_management

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
mantisbt/gitosis_management.txt · Last modified: 2008/11/07 02:16 by vboctor

Driven by DokuWiki