====== 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: <code>git@mantisbt.org:<repository>.git</code> Public repositories have a separate clone URL that uses an unauthenticated connection to allow cloning the repository without any permissions check: <code>git://mantisbt.org/<repository>.git</code> ==== 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. <code> $ git clone git@mantisbt.org:gitosis-admin.git </code> 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. <code> $ git commit -a -m "<What you just did>" $ git push </code> 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. <code> $ cd gitosis-admin </code> Edit ''gitosis.conf'' and add a section to the end of the file with the following contents: <code> [repo myplugin] description = A plugin for the Mantis Bug Tracker. owner = John Smith [group myplugin] writable = myplugin members = jsmith @core </code> 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: <code> $ cat > keydir/jsmith.pub ... ^D </code> Now you need to add and commit your changes to the repository, and then push your commit back to the server: <code> $ 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 </code> 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: <code> $ cd /path/to/myplugin $ git remote rm origin $ git remote add origin git@mantisbt.org:myplugin.git $ git push origin master </code> 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: <code> # sudo chmod 755 ~git/repositories/myplugin.git </code> Next we need to symlink to the repository from a location where git-daemon and gitweb are both looking for shared repos: <code> # sudo ln -s ~git/repositories/myplugin.git /var/cache/git/ </code> 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) <code> # 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 </code>

Logged in as: anonymous
mantisbt/gitosis_management.txt · Last modified: 2008/11/07 02:16 by vboctor