What is it?Git is a fast, scalable, distributed revision control system. For the purpose of this document, the owner of the shared git repository is called 'shared user'. Other users who are granted access to the 'shared user' account are called 'end users'. Gitosis is a helper program that allows a 'shared user' account to host Git repositories and give 'end users' different access levels to them using SSH and SSH keys. From the README file: gitosis aims to make hosting git repos easier and safer. It manages multiple repositories under one user account, using SSH keys to identify users. End users do not need shell accounts on the server, they will talk to one shared account that will not let them run arbitrary commands. End users can then 'clone' a copy from the master and run git related commands on the local copy per usual to manage file or directory objects within the repository. Where git is not installed on a given server, it would not be possible to access shared git repositories set up under gitosis. The README file for gitosis (at /usr/share/doc/gitosis/README.rst.gz) explains how to set up a gitosis service running from a special account directory. Instead, most people at CSE will use their own account to host their Git repositories. This will require a more specific setup, described below. gitosis and git packages are installed on CSE login servers and most lab machines, allowing access to shared git repositories via these servers. Documentation also mentioned that the shared user account doesn't need to have a password, but does need to have a valid shell for SSH to work.
Quick Start Guide
Create Admin Key and Initialise GitosisYou 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/gitosiskeyThis creates keyfiles in your .ssh/ directory: gitosiskey, gitosiskey.pub. This is the key you use for admin operations on your Gitosis service. Initialise Gitosis:
gitosis-init < ~/.ssh/gitosiskey.pubThis creates directories gitosis/, 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.
Admin AccessYou now have admin access to your Gitosis service using the admin key you created above. Make sure the key is registered in your SSH agent before you do the next bit. If you are logged into an account other than the 'shared user' account then you can do this:
git clone email@example.com:gitosis-admin.git… where shared-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. Accessing a Gitosis service in your CSE account when you are using your CSE account is tricky as ssh won't default to using the key file linked to Gitosis. Instead it will log you straight into a shell. So, the workaround would be to create a wrapper script for SSH. Create a file ~/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 fiThen use it with git commands with the GIT_SSH environment variable set:
export GIT_SSH=/path/to/gitosis-ssh.shThen you can access the gitosis-admin repository. For other Git repositories in your account you can use Git on them directly rather than going via SSH and Gitosis.
Adding New Users and AccessTo add new users:
- clone the gitosis-admin repository to your current login.
- Add a file keys/<username>.pub. This should be the SSH public key to person wants to use.
- Authorize <username> to readonly/writeable repositories as needed (or just authorize the group @all) See next section for an example.
- Edit the settings as you wish, commit and push. Once you push, Gitosis will immediately make your changes take effect on the shared-user account.
Create New RepositoryTo create new repositories, just authorize writing to an 'end user' and git-push the configuration change and a new project. From the README file:
For example: let's assume your username is jdoe and you want to create a repository myproject. In your clone of gitosis-admin, edit gitosis.conf and add:
[group myteam] members = jdoe writable = myprojectCommit that change and push using the admin key. Then create the initial commit and push it:
mkdir myproject cd mypyroject git init git remote add myserver firstname.lastname@example.org:myproject.gitDo some work, git add and commit files
git push myserver master:refs/heads/masterThat's it. If you now add others to members =, they can use that repository too.
ConfigurationHighlighted below are few areas of configuration worth noting:
- gitosis relies on SSH keys to allow end users to share git repositories hosted under a shared user account.
Public key entries inserted by gitosis are restricted to allow only certain commands to run.
They are appended to the <shared user>/.ssh/authorized_keys.
Any existing keys in the <shared user>/.ssh/authorized_keys file would be left intact. Below is a typical default key entry (of type DSA) inserted by gitosis:
command="gitosis-serve <username>@<server>",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-dss [ ...<public key code>...] <username>@<server>Note the 'gitosis-serve' command is relative and should be modified to full path '/usr/bin/gitosis-serve' for added security.
command="/usr/bin/gitosis-serve <username>@<server>",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-dss [ ...<public key code>...] <username>@<server>Apart from that, unless you know what you're doing, the inserted key entries must NOT be modified in other ways otherwise security can potentially be unnecessarily compromised due to intentional/unintentional changes.
End user's public key is copied to <shared user>/repositories/gitosis-admin.git/gitosis-export/keydir without the .pub extension.
To grant an end user access to the shared user's repository, just add the end user's public key to the keydir folder, and then give the user permissions by modifying gitosis.conf (see next).
gitosis configuration lives in <shared user>/repositories/gitosis-admin.git/gitosis.conf
Here can specify access control (eg. readonly, read/write) of end users to each shared repository.
[group developers] members = todd bill writable = project1 project2 [group webguys] members = travis chris readonly = project1In this instance, travis and chris only have read access to the project1 repository, whereas todd and bill have full write access to project1 and project2.
Precautions & Good PracticesDue to possible security risks associated with SSH keys, usual care should be exercised including the following:
As far as possible only public keys associated with local CSE accounts should be used, not those created from remote like from home PCs etc.
This should be true in general not just those end user accounts who intend to use gitosis.
Due to the way course class accounts are set up, they are NOT to be used for hosting shared git repositories.
See further details in Taggi page SSH authorized keys for course class accounts.
- Normal group accounts (see taggi page Group accounts for further details) belonging to Utility class are typically set up for file sharing and/or web hosting within a user group and either with nologin (no SSH access) or with SSH access. Those with nologin access are not suitable for hosting shared git repositories since a valid login shell is required for SSH to work. In this case, should you think otherwise and have a burning case to use the group account for shared git repositories, please consult Systems Support to discuss the best way forward.
Each local copy of git repository would be owned by the respective end user, so disk quota would be charged against the end user's account and subjected to whatever constraints and behaviours in the usual way.
The same applies to the shared copy of git repository under gitosis which is owned by the shared user.
In any case, it's important to allocate enough disk space to cover the anticipated usage for both the shared user account and the end user accounts.
- For configuration variables that can apply globally such as daemon in the gitosis config file gitosis.conf, extra care should be exercised as all repositories are affected. Where supported, per-repository scope should be used instead wherever possible for better control and minimising unnecessary 'side-effects'.
- See readme and others in /usr/share/doc/gitosis.
- Git related man pages eg. git(1), git-clone(1), gittutorial(7), gittutorial-2(7), etc.