What is it?

Gitosis is a helper program provding user-managed access control to Git repositories.

Ordinarily, users wanting access to your Git repo would need filesystem access to the repository itself.

This would require that those other users have their own account on the system, and be in the correct unix group.

Gitosis allows you to grant very limited, repository-only access to other users via SSH keys instead.

This works even for people without their own login accounts on the system.

Quick Start Guide

Creating the admin Key

You can use an existing SSH key but access can be easier to manage with a distinct key that you use just for Gitosis:

ssh-keygen -f ~/.ssh/gitosiskey

This creates keyfiles in your .ssh/ directory: gitosiskey, gitosiskey.pub.

This is the key you use for admin operations on your Gitosis service.

Initialising Gitosis:

gitosis-init < ~/.ssh/gitosiskey.pub

This creates the directories gitosis/ and repositories/.

It also sets entries in your ~/.ssh/authorized_keys file to run gitosis-serve when someone uses an SSH key you've associated with Gitosis.

Administering Gitosis

You now have admin access to your Gitosis service using the admin key you created above.

The confguration for Gitosis is actually kept it its own Git repository that you can check out, modify then check back in.

Make sure the key is registered in your SSH agent before you do the next bit.

With the respository in a separate account

If you have the repository in a separate account (for instance, a utility account), you can go ahead and clone the repository directly:

git clone user@cse.unsw.edu.au:gitosis-admin.git

...where user is the account you ran gitosis-init in above.

This gives you a copy of the configuration files for Gitosis.

SSH keys for access will be called keys/<username>.pub and there is a gitosis.conf file where you can configure who has access to what.

With the repository in your personal account

Connecting to Gitosis in your own CSE account is a little trickier, as ssh won't use the Gitosis key by default, and so won't talk to the right service.

To work around this, create a wrapper script for SSH - ~/bin/gitosis-ssh.sh:

#!/bin/sh
KEYFILE=~/.ssh/gitosiskey

if ssh-add "$KEYFILE"; then
 ssh -o HostbasedAuthentication=no -i "$KEYFILE" "$@"
else
 echo No ssh-agent running. Cannot git-ssh. >&2
 exit 1
fi

Then use it with git commands with the GIT_SSH environment variable set:

export GIT_SSH=/path/to/gitosis-ssh.sh

Then you can access the gitosis-admin repository as in the previous section.

For other Git repositories in your account you can use Git on them directly rather than going via SSH and Gitosis.

Managing users and repositories

Access to shared repositories is managed by files in the gitosis-admin repository.

Each stanza in gitosis.conf represents a user group, with entries for the group members and the repositories they can access:

[group group1]
members = user1 user2
readonly = repo1
writeable = repo2 repo3

[group group2]
members = user3 user4
readonly = repo2 repo3

To create a new group, just create a new stanza in gitosis.conf.

To add a new user, put their public key into keys/<username>.pub, and add their username to the members line for the relevant groups in gitosis.conf.

To add the config for a new repository, add the name of the new repository to the writeable list for your username.

When you're done making changes, commit and push gitosis-admin to implement them.

To actually create the new repository itself, create the initial commit and push it:

mkdir myproject
cd myproject
git init
git remote add myserver user@cse.unsw.edu.au:myproject.git

Do some work, git add and commit files, then:

git push myserver master:refs/heads/master

Notes

Public key security

Gitosis inserts specially-restricted public keys for users into /home/<user>/.ssh/authorized_keys:

command="gitosis-serve <username>@<server>",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-dss
 [ ...<public key code>...] <username>@<server>

For security reasons, it's best to edit gitosis-serve to the full path: /usr/bin/gitosis-serve

However, you really shouldn't edit anything else, as it's really easy to mess up your account security if you get it wrong.

Wherever possible, you should always use the public key from people's CSE account, rather than from their personal or work computers.

Course accounts

Course accounts should not be used for hosting shared git repositories, since changes to their authorized_keys file will get reverted overnight.

See SSH authorized keys for course class accounts for details.

Miscellaneous config

Be careful with config variables such as [daemon] in gitosis.conf, as they can apply to all repositories.

Where possible, use per-repository scope to avoid unexpected side-effects.

Gitosis