`gitosis` -- software for hosting `git` repositories

Manage git repositories, provide access to them over SSH,with tight access control and not needing shell accounts.

Note

Documentation is still lacking, and non-default configurations(e.g. config file, repositories, installing in a location thatis not in PATH) basically have not been tested at all.Basic usage should be very reliable -- the project has beenhosting itself for a long time. Any help is welcome.

gitosis aims to make hosting git repos easier and safer. Itmanages multiple repositories under one user account, using SSH keysto identify users. End users do not need shell accounts on the server,they will talk to one shared account that will not let them runarbitrary commands.

gitosis is licensed under the GPL, see the file COPYING formore information.

You can get gitosis via git by saying:

git clone https://github.com/tv42/gitosis.git

And install it via:

python setup.py install

Though you may want to use e.g. --prefix=.

Setting up

First, we will create the user that will own the repositories. This isusually called git, but any name will work, and you can have morethan one per system if you really want to. The user does not need apassword, but does need a valid shell (otherwise, SSH will refuse towork). Don't use an existing account unless you know what you'redoing.

I usually store git repositories in the subtree/srv/example.com/git (replace example.com with your owndomain). You may choose another location. Adjust to suit and run:

sudo adduser \    --system \    --shell /bin/sh \    --gecos 'git version control' \    --group \    --disabled-password \    --home /srv/example.com/git \    git

This command is known to work in Debian and Ubuntu. Your mileage mayvary.

You will need an SSH public key to continue. If you don't have one,you need to generate one. See the man page for ssh-keygen, and youmay also be interested in ssh-agent. Create it on your personalcomputer, and protect the private key well -- that includes nottransferring it over the network.

Next, we need to set things up for this newly-created user. Thefollowing command will create a ~/repositories that will hold thegit repositories, a ~/.gitosis.conf that will be a symlink tothe actual configuration file, and it will add the SSH public key to~/.ssh/authorized_keys with a command= option that restrictsit to running gitosis-serve. Run:

sudo -H -u git gitosis-init <FILENAME.pub# (or just copy-paste the public key when prompted)

then just git clone git@SERVER:gitosis-admin.git, and you get arepository with SSH keys as keys/USER.pub and a gitosis.confwhere you can configure who has access to what.

Warning

For now, gitosis uses the HOME environment variable tolocate where to write its files. If you use sudo -uwithout -H, sudo will leave the old value of HOMEin place, and this will cause trouble. There will be aworkaround for that later on, but for now, always remember touse -H if you're sudoing to the account.

You should always edit the configuration file via git. The filesymlinked to ~/.gitosis.conf on the server will be overwrittenwhen pushing changes to the gitosis-admin.git repository.

Edit the settings as you wish, commit and push. That's pretty much it!Once you push, gitosis will immediately make your changes takeeffect on the server.

Managing it

To add new users:

add a keys/USER.pub file
authorize them to read/write repositories as needed (or justauthorize the group @all)

To create new repositories, just authorize writing to them andpush. It's that simple! For example: let's assume your username isjdoe and you want to create a repository myproject.In your clone of gitosis-admin, edit gitosis.conf and add:

[group myteam]members = jdoewritable = myproject

Commit that change and push. Then create the initial commit and pushit:

mkdir myprojectcd mypyrojectgit initgit remote add myserver git@MYSERVER:myproject.git# do some work, git add and commit filesgit push myserver master:refs/heads/master

That's it. If you now add others to members, they can use thatrepository too.

Example configuration

Using `git daemon`

Anonymous read-only access to git repositories is provided bygit daemon, which is distributed as part of git. Butgitosis will still help you manage it: setting daemon = yes inyour gitosis.conf, either globally in [gitosis] orper-repository under [repo REPOSITORYNAME], makes gitosiscreate the git-daemon-export-ok files in those repository, thustelling git daemon that publishing those repositories is ok.

To actually run git daemon in Ubuntu, put this in/etc/event.d/local-git-daemon:

For other operating systems, use a similar invocation in an init.dscript, /etc/inittab, inetd.conf, runit, or something likethat (good luck).

Note that this short snippet is not a substitute for reading andunderstanding the relevant documentation.

Using gitweb

gitweb is a CGI script that lets one browse git repositorieson the web. It is most commonly used anonymously, but you could alsorequire authentication in your web server, before letting people useit. gitosis can help here by generating a list of projects thatare publicly visible. Simply add a section [repo REPOSITORYNAME]to your gitosis.conf, and allow publishing with gitweb = yes(or globally under [gitosis]). You should also set descriptionand owner for each repository.

Here's a LightTPD config file snippet showing how to run gitwebas a CGI:

And a simple gitweb.conf file:

Note that this short snippet is not a substitute for reading andunderstanding the relevant documentation.