tv42/gitosis

software for hosting git repositories

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 that is not in PATH) basically have not been tested at all. Basic usage should be very reliable -- the project has been hosting itself for a long time. Any help is welcome.

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.

gitosis is licensed under the GPL, see the file COPYING for more 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 is usually called git, but any name will work, and you can have more than one per system if you really want to. The user does not need a password, but does need a valid shell (otherwise, SSH will refuse to work). Don't use an existing account unless you know what you're doing.

I usually store git repositories in the subtree /srv/example.com/git (replace example.com with your own domain). 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 may vary.

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 you may also be interested in ssh-agent. Create it on your personal computer, and protect the private key well -- that includes not transferring it over the network.

Next, we need to set things up for this newly-created user. The following command will create a ~/repositories that will hold the git repositories, a ~/.gitosis.conf that will be a symlink to the actual configuration file, and it will add the SSH public key to ~/.ssh/authorized_keys with a command= option that restricts it 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 a repository with SSH keys as keys/USER.pub and a gitosis.conf where you can configure who has access to what.

Warning

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

You should always edit the configuration file via git. The file symlinked to ~/.gitosis.conf on the server will be overwritten when 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 take effect on the server.

Managing it

To add new users:

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

To create new repositories, just authorize writing to them and push. It's that simple! 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 = myproject

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

mkdir myproject
cd mypyroject
git init
git remote add myserver git@MYSERVER:myproject.git
# do some work, git add and commit files
git push myserver master:refs/heads/master

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

Example configuration

Using git daemon

Anonymous read-only access to git repositories is provided by git daemon, which is distributed as part of git. But gitosis will still help you manage it: setting daemon = yes in your gitosis.conf, either globally in [gitosis] or per-repository under [repo REPOSITORYNAME], makes gitosis create the git-daemon-export-ok files in those repository, thus telling 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.d script, /etc/inittab, inetd.conf, runit, or something like that (good luck).

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

Using gitweb

gitweb is a CGI script that lets one browse git repositories on the web. It is most commonly used anonymously, but you could also require authentication in your web server, before letting people use it. gitosis can help here by generating a list of projects that are 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 description and owner for each repository.

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

And a simple gitweb.conf file:

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

Contact

You can email the author at [email protected], or hop on irc.freenode.net channel #git and hope for the best.

There will be more, keep an eye on http://eagain.net/ and/or the git mailing list.

gitosis's Issues

Can't clone gitosis-admin.git after initail gitosis with root's id_rsa.pub

On a server machine, I init gitosis with the root's public key, and git clone git@host:gitosis-admin.git, and terminal prompted me to input git's password, it just can't clone gitosis-admin.git.

Then I deluser git and init gitosis with a local machine's id_rsa.pub, and clone gitosis-admin.git in the same machine, everything just fine.

So, can I manage gitosis-admin.git in the same machine after init?
btw, how to read gitosis?
[git to sys]?

any help is greatly appreciated.

setup.py version doesn't match release tag

setup.py still reports version 0.2.

fatal: 'repo-name.git' does not appear to be a git repository

When i create the repository, at the moment to execute the git push is given a fatal error
fatal: 'repo-name.git' does not appear to be a git repository
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

i have regenerated the public key lot of times, refollowed all the steps and this error continues

_ACCEPTABLE_USER_RE is overly strict

By my reading of ssh.py and sshd(8), section "AUTHORIZED_KEYS FILE FORMAT", the risks being blocked by this username validation are:

• Double-quote: would close the command= option
• Backslash and comma: potentially risky because the parsing isn't clearly specified
• Whitespace: would prematurely terminate the username argument to gitosis-serve
• Shell special characters: unspecified whether sshd runs the command through a shell so best to assume it does; also the user is passed to hooks through the GITOSIS_USER environment variable
• Non-printable-ASCII characters: uncertain

The last two suggest that the exact set of safe characters is system- and perhaps even locale-dependent. Nonetheless, we can say for certain that what constitutes a valid username, hostname, or email address on any particular system does not enter into it.

I got bit by this, and I'm not the only one, so might I suggest the more permissive yet still conservative regexp:

^[a-zA-Z0-9@_.-]+$

Incidentally, this is closer to what one might have expected from reading the commit message on cbea178.

A risk would be if people have built hooks using GITOSIS_USER that rely on the current validation. Given that it's not documented as any sort of stable thing, I would suggest that such users should either be doing their own validation or else looking closely for any changes that might affect their assumptions before upgrading.

Comment and empty lines not ignored in public key files

Per sshd(8), on the authorized_keys file format:

Each line of the file contains one key (empty lines and lines starting with a `#' are ignored as comments).

Perhaps one shouldn't assume that gitosis keydir/*.pub files use an identical format; still, it would be less surprising if comments and empty lines were recognized. Currently you can end up with junk like:

command="gitosis-serve test",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty # test comments, empty lines
command="gitosis-serve test",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty 
command="gitosis-serve test",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa AAA...== test

Is tv42/gitosis the official gitosis repo?

I saw the following error when trying to use eagain.net:

git clone git://eagain.net/gitosis.git
Cloning into 'gitosis'...
fatal: unable to connect to eagain.net:
eagain.net[0: 192.237.217.227]: errno=Connection refused
eagain.net[1: 2001:4800:7813:516:fa64:3a5d:ff04:7851]: errno=Network is
  unreachable

progit/progit#668

Fix for gitosis in ubuntu 12.04 (which didn't work before the fix)

Hello!
In Ubuntu 12.04 the hooks didn't work. Pushing to the gitosis-admin repo didn't
refresh the config file or the ssh keys.

There were two problems with the post-update hook for the gitosis-admin repo.

1. It wasn't executable, and needed chmod +x

         chmod +x  <gitosis_home>/repositories/gitosis-admin.git/hooks/post-update

2. It used old git commands, which are found now in '/usr/lib/git-core' as symlinks.
   The fix for that is to add:

         PATH=$PATH:/usr/lib/git-core
         export PATH

to the first lines of the 'post-update' hook.

After this, it works like a charm.
Please include the fix if you can, so that other people can use gitosis in ubuntu.
Thanks so much for gitosis!!!!

New release?

Hi, the last release was 8 years ago. Would you mind making a new one so we can package it in Arch?

Consider refering to dockerized version of gitosis

Perhaps the documentation can refer to https://github.com/thomergil/gitosis-docker

gitosis missing in EPEL7

Where I can find rpm package for gitosis at CentOS7 ? For CentOS6 I found in EPEL6, but in EPEL7 missing. Why?

Thanks

Reject invalid gitosis configurations

If you push an update of gitosis-admin with an invalid gitosis.conf file, you can't access any repositories anymore, you will always receive a ConfigParser.ParsingError until you fix the gitosis,conf on the server.

There should be a protection:
When the gitosis-admin repository receives an update, the gitosis.conf should be checked if it is still valid, if not, then the update should be rejected.