[[PageOutline(2-5,Contents,pullout)]]

= Gitosis administration plugin

== Description

This plugin allows partial [https://github.com/tv42/gitosis Gitosis] administration from Trac. Gitosis is a tool which provides access control and remote management for hosted Git repositories. Gitosis itself is GPL licensed.

Key features:
* Users will be able to add their public SSH key in Gitosis in a new settings tab.
* Admins will be able to set the location of the gitosis-admin repository and settings for the Git repository associated with Trac (requires GitPlugin).

More information on Gitosis can be found [https://en.wikibooks.org/wiki/Git/Gitosis here].

== Bugs/Feature Requests

Existing bugs and feature requests for TracGitosisPlugin are 
[report:9?COMPONENT=TracGitosisPlugin here].

If you have any issues, create a 
[/newticket?component=TracGitosisPlugin new ticket].

[[TicketQuery(component=TracGitosisPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [https://github.com/dr4Ke/TracGitosisPlugin/archive/latest.zip GitHub].

== Source

You can check out TracGitosisPlugin as follows:

{{{#!sh
$ git clone git://github.com/dr4Ke/TracGitosisPlugin.git
}}}

Alternatively, [http://github.com/dr4Ke/TracGitosisPlugin browse the source] on !GitHub.

== Configuration

Before this plugin can work, you need a few things:
 - a working git installation on the server running Trac
 - SSH key pair without passphrase for the user running Trac
 - access to a gitosis-admin repository

=== SSH key pair

Example on a RHEL server using Apache httpd :
{{{#!sh
# Create the key pair without passphrase
mkdir /var/www/.ssh
ssh-keygen -f /var/www/.ssh/id_rsa
# Connect to the server hosting gitosis once to validate the server identity
ssh -i /var/www/.ssh/id_rsa -o UserKnownHostsFile=/var/www/.ssh/known_hosts <git_user>@<git_server>
# Give this directory to the user running Trac (here: apache)
chown -Rh apache.apache /var/www/.ssh
}}}

=== Configure access to gitosis-admin

Simply add the previously generated public key in the file {{{keydir/trac.pub}}} and add the user {{{trac}}} in the {{{gitosis-admin}}} group members in the {{{gitosis.conf}}} file as for a standard gitosis admin. Then commit and push your changes. That should do it.

== Configuration into Trac

You have to enable the plugin (and restart Trac) with this parameter in {{{trac.ini}}}:
{{{#!ini
[components]
tracgitosis.* = enabled
}}}

Next, in the Admin panel, you'll see two pages in a new {{{Trac Gitosis}}} section:
 - Admin Settings
 - Repository Settings

In the {{{Admin Settings}}}, you must give gitosis-admin access parameters before you can actually use this plugin:
||Parameter||Default value||Description||
||Admin Repository Name||gitosis-admin||the name of the gitosis administration special repository||
||User||git||System username for access on the gitosis repositories||
||Server||localhost||Server hosting gitosis repositories||

Save changes and enjoy the {{{Repository Settings}}} (for admins only) and the {{{gitosis SSH public key}}} in all users preferences.

== Usage

When accessing either {{{Repository Settings}}} or {{{gitosis SSH public key}}} for the first time, Trac clones the gitosis-admin repository at the root of the trac project.

Then, each time these pages are displayed, the repository is pulled in order to read current settings and public keys. When you press {{{Save changes}}}, the repository is pulled again, settings are written into {{{gitosis.conf}}}, public key is written into {{{keydir/<user>.pub}}}, changes are committed and pushed to the main admin repository.

'''Warning'''

The gitosis file is overwritten each time setting are saved in Trac using a modified !ConfigParser Python class. The [gitosis] section will be written first. All other sections will be written in a sorted way. In each section, the parameters are written the same sorted way.

In short, this means:
 - sections and parameters will be moved if they were not sorted in the original file 
 - all comments will be lost, because I don't know were to write them after section and/or parameters moved

== Recent Changes

See [http://github.com/dr4Ke/TracGitosisPlugin/commits/master GitHub history]

== Author/Contributors

'''Author:''' [wiki:dr4Ke] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''