Gitosis

From ArchWiki
Revision as of 07:35, 20 August 2009 by Djszapi (Talk | contribs) (public SSH key generation command was added)

Jump to: navigation, search

Template:I18n links start Template:I18n entry Template:I18n entry Template:I18n links end

What is gitosis?

gitosis is simply an access control list for git, the (famous) stupid content tracker. Once you have a git repository, there are many ways to setup how people will access it. You might prefer publishing your repository with read-only access via the git:// protocol. But when it comes to pushing to the repository, it's essential to decide by whom and how the repository will be accessed. Generally, you wouldn't prefer letting everyone pushing changes and hopefully ruin your repository. Therefore you need some kinds of authorization methods such as:

  • SSH Authentication
  • HTTP Authentication (webdav)
  • gitosis (using SSH)

The rest of this document is about the third method. (Afterall, the title says it all.)

What does gitosis do?

With gitosis, you have the ability to pull from and push to the repository with just one system account. You don't need to create SSH accounts for each user who will have write access to the repository. Once you install the package (see below), there will be system user created on your system called gitosis with a home directory in /srv. Users that will access to the repositories will be using gitosis user for every transaction.

How to install gitosis?

I've just packaged gitosis in AUR with the name gitosis-git. You can simply download the necessary files and build the package using makepkg or simply use yaourt to install it. You need git, python and setuptools packages installed on your computer in order to compile and install gitosis. They're also defined as dependencies in the PKGBUILD. Once installed, you'll be able to find some example config files in /usr/share/doc/gitosis.

Initiating gitosis-admin repository

You will need a public SSH key to continue. If you don't have one, you may generate one on your local computer:

$ ssh-keygen -t rsa

In order to make gitosis work, you should first create a SSH key pair (or use the existing one) and use the public key to create the gitosis-admin repository installed within gitosis home directory (/srv/gitosis).

$ sudo -H -u gitosis gitosis-init < /path/to/public_key.pub
Initialized empty Git repository in /srv/gitosis/repositories/gitosis-admin.git/
Reinitialized existing Git repository in /srv/gitosis/repositories/gitosis-admin.git/

You should also place the public key you used above as .ssh/authorized_keys inside gitosis' home directory. The above command will create two directories:

  • gitosis
  • repositories

The directory gitosis includes a single file (projects.list) in which some information about the repositories are defined. The repositories directory contains all repositories including the gitosis-admin repository.

gitosis-admin repository

gitosis-admin is simply a git repository, that stores the permissions per repository and the keys of users who have access to them. To change the settings of gitosis, add/remote repositories or users, you'll need to clone the repository to some local directory and do the changes like you would do to a normal git repository. After you're done with the files, you'll have to commit the changes and push them to the remote repository you initially cloned from.

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

For this command to work,

  • the home directory (/srv/gitosis/) => 700
  • the .ssh directory (/srv/gitosis/.ssh/) => 700
  • the authorized_keys file (/srv/gitosis/.ssh/authorized_keys) => 600

should have the correct permissions. Once you clone the repository, you'll be able to edit the following:

  • gitosis.conf
  • keydir
    • user_ssh_key.pub

configuration of the repositories

gitosis.conf

[gitosis]
gitweb = yes

[repo foobar]
description = git repository for foobar
owner = user

[group devs]
members = user1 user2

[group admins]
members = user1

[group gitosis-admin]
writable = gitosis-admin
members = @admins

[group foobar]
writable = foobar
members = @devs

gitosis repositories can also be used with gitweb; just point the directory that contains the repository inside the gitweb configuration.

  • [repo] blocks are used to define some necessary areas being used with gitweb.
  • [group] blocks are used for both:
    • defining user groups
    • defining repository permissions
  • @ is used to define user groups.

You should commit and push any changes you do in this file.

keydir

keydir is simply a directory that contains public keys of the users. Some of the keys can be in the form of user@machine and those keys must be defined with that form inside gitosis.conf. It's better to create user groups and use them as members of the repositories. Once you add new keys to enable some new users, you should add the files to the git repository and commit & push them. The new users will use the above form of git commands like you've used to clone the gitosis-admin repository.