FreeBSD and Debian. Installing and Configuring Gitosis · English

Over time, I switched from Mercurial to Git; I’ll explain why in another article. Today, I’ll explain how to set up authentication and repository access controls using Gitosis.

Installing and Configuring Git

In any case, we’ll need to create a “git” group and user, and install Git.

FreeBSD:


pw group add git
adduser git
cd /usr/ports/devel/git
make && make install

Debian:


groupadd git
useradd -g git git
apt-get install git

Installing and Configuring Gitosis

We chose Gitosis at work some time ago, and we haven’t been disappointed. It’s a fairly simple solution based on Git hooks and SSH keys, which gives us the most important thing: per-project access controls.

Keeping all users’ public keys in authorized_keys to grant access works well only for a while. When you have hundreds of users, it’s more like torture. You have to log into the server every time, and there are no access controls—everyone listed in the file has read and write access to every project. At this stage, you may want to turn to a widely used piece of software called Gitosis. Gitosis is simply a set of scripts that helps you manage the authorized_keys file and implement basic access control. What’s really interesting is that the interface for adding people and defining their access with this tool isn’t a web interface, but a special Git repository. You configure the information in this project, and when you push it to the repository, Gitosis reconfigures the server based on it, which is cool. Pro Git - Pro Git 4.7 Git on the Server Gitosis

In short, authentication will be key-based, and gitosis will control the permissions policy. Let’s go!

Installing Gitosis

FreeBSD:


cd /usr/ports/devel/py-gitosis/
make install clean

Debian:


apt-get install gitosis

You can also install it from source, but since gitosis development stopped in the fall of 2009, you won’t get anything newer anyway:


git clone git://eagain.net/gitosis.git gitosis
cd gitosis
sudo python setup.py install

Configuring Gitosis

First, we need to create a key on the local machine and copy it to the server:


ssh-keygen -C “<username>” -t rsa
scp ~/.ssh/id_rsa.pub <username>@example.org:key_for_gitosis.pub
mv ~/.ssh/id_rsa ~/.ssh/gitosis

Now add the following to your local “.ssh/config”:


Host gitosis
    User git
    Hostname <hostname>
    IdentityFile ~/.ssh/gitosis

Next, log into the server and initialize gitosis:


sudo su - git
gitosis-init < /home/<username>/key_for_gitosis.pub
Initialized empty Git repository in /home/git/repositories/gitosis-admin.git/
Reinitialized existing Git repository in /home/git/repositories/gitosis-admin.git/

Let’s return to the local machine and try connecting:


ssh git@gitosis -T
>> ERROR:gitosis.serve.main:Need SSH_ORIGINAL_COMMAND in environment.

If you get a response something like this, everything is fine—let’s continue!

Now let’s clone the “gitosis-admin” repository locally and edit the configuration file:


git clone git@gitosis:gitosis-admin.git gitosis-admin

In the resulting repository, you’ll see a “keydir” directory, which stores all the public keys of users who have access to the repositories. To add a user, you need to put the public key they generated there, and then add a reference to that user in the “members” section of “gitosis.conf”.

To create a new repository, log into the server and run:


cd ~/repositories
mkdir someproject.git && cd someproject.git/
git init --bare
>> Initialized empty Git repository in /home/git/repositories/someproject.git/

Next, let’s add something like this to the local “gitosis.conf” file:


[group developers]
writable = someproject
members = adw0rd <another-username>

It’s also possible to inherit users from another group, for example:


[group developers]
members = adw0rd example

[group project]
writable = project
members = @developers tester

In short, under “members” you need to list the users who have access to the repository specified under “writable”. And add the public keys received from those users to “keydir”. That’s all you need!

To debug gitosis itself, you may need this option:


[gitosis]
loglevel=DEBUG

Gitosis reads its settings from “/home/git/.gitosis.conf”, which is a symlink to “/home/git/repositories/gitosis-admin.git/gitosis.conf”. So you can always modify the gitosis configuration file, even if you’ve lost external access to it, by manually editing “/home/git/repositories/.gitosis.conf”.

I also recommend reading Gitosis - ArchWiki.