Overview

The Academic Computing Gitosis service is a tool that provides SEAS users, group, and labs secure, manageable, and centralized access to git repositories. It relies on the use of SSH and public/private keys to delegate operational control of a set of repositories to individuals in the SEAS community. These repositories can be public or private, and control can be managed as needed by their owners.

For more on gitosis, see the technical article

• Hosting Git repositories, The Easy (and Secure) Way

For more on Git, please see the documentation

• Introduction To GIT

Method

Git combined with Gitosis uses a user's public keys as the means of identifying and authenticating a user. Access to repositories is granted based on the signature of the key presented. Thus, basic knowledge of SSH and SSH keys is needed in order to use this service. For informationon SSH and SSH key authentication, please see the document here:

• SSH Access to SEAS Hosts

Initial Setup

To start using gitosis, you will need to have created for you or your lab, course, or collaboration an instance of gitosis, which represents group of repositories (or "repository group"). This is essentially a set of configurations and credentials that you will control, and into which can be created any number of repositories and users.

To request a gitosis "repository group", please send an email to

• achelp@seas.harvard.edu

And include the following information:

1. The desired name of group (i.e. "cs123" or "brown-vlci-lab")
2. An initial public SSH key that will be used for administrative access to the repository group.

Repository Group Management

Once the repository group is created by Academic Computing staff, we will send you in an email the command to checkout the configuration for your repository group. This will be something like this:

git clone cs123@git.seas.harvard.edu:gitosis-admin.git

This repository is special in that it contains all the configuration options for this repository group. By modifying the files in this repository, you control access to all other repositories in this repository group.

Once the repository is cloned, you can begin to add other's keys to the configuration, and grant them access as well. Assuming that you've successfully been able to check out the gitosis-admin repository, it should look something like this:

$ cd ./gitosis-admin
$ ls -l
total 16
-rw-r--r--  1 parrott  staff  154 Jan 25 14:28 gitosis.conf
drwxr-xr-x  6 parrott  staff  204 Jan 25 14:27 keydir

$ ls -l keydir
-rw-r--r--  1 parrott  staff  406 Jan 25 14:24 parrott@seas.harvard.edu.pub

The directory keydir is where you put any additional public key for other users. For convention, these public keys should be named as follows

• username@host or domain.pub

Once added, access to a repository is managed by modifying the gitosis.conf file and referring to one of the keys. As an example, suppose we add another user with email address lars@seas.harvard.edu to the repository group, and want to grant him administrator rights, and he provides a key named id_rsa.pub which is in a /tmp directory. Then we do the following to a clean installation to grant him the proper privileges:

$ cd ./gitosis-admin
$ cp /tmp/id_rsa.pub ./keydir/lars@seas.harvard.edu.pub
$ git add ./keydir/lars@seas.harvard.edu.pub

Next we need to edit gitosis.conf to add the string lars@seas.harvard.edu to the correct line. The file gitosis.conf would now look like this:

[gitosis]

[group gitosis-admin]
writable = gitosis-admin
members = parrott@seas.harvard.edu lars@seas.harvard.edu

Note that we dropped the .pub from the filename. Once the file looks right, we save and push all our changes:

$ git add gitosis.conf
$ git commit -m "Added lars@seas.harvard.edu as gitosis admin"
$ git push

Once done, the user who gave you the public key can now clone, edit and push the gitosis-admin.git repository, which in turn means that they can administer the repository group.

Adding Repositories

To add a repository to a repository group, you add a record for it to the gitosis-admin configuration. While not completely intuitive, the process is simple. The syntax look just like that of the gitosis-admin repository.

To create a new repository, and grant "parrott@seas.harvard.edu" and "lars@seas.harvard.edu" access, you would add the following stanza to the end of the gitosis.conf file:

[group my_group_name]
members = parrott@seas.harvard.edu lars@seas.harvard.edu
writable = big_project

Once added and the change committed and pushed, then one can add files to the "big_project" repository. Create a fresh repository on your system, do some work, add some files, and then push:

$ mkdir big_project
$ cd big_project
$ git init
$ git remote add origin cs123@git.seas.harvard.eduE:big_project.git
...
# do some work, git add and commit files
...
$ git push origin master

Here we've created a fresh project, hooked it up to the empty repository in our repository group, and then pushed all the local changes to the server.

Now on another system, user lars@seas.harvard.edu can clone the repository:

$ git clone cs123@git.seas.harvard.edu:big_project.git 

And pull down all the committed and pushed changes from the other user.

Public Access

Repository browsing via the web

To make a repository available to the public via a web browser (using gitweb), you need to add a repo stanza to your gitosis.conf file. For example, to expose your big_project repository, you would add the following:

[repo big_project]
daemon = yes
description = A big, big very big project.

The line daemon = yes is what exposes this repository via the web interface. The description field provides a short description that will be visible in the web interface.

You can access your publicly browseable repositories at http://git.seas.harvard.edu/groupname/. For example, if you access repositories via ssh as cs123@git.seas.harvard.edu, the URL would be http://git.seas.harvard.edu/cs123/.