1 ==========================================================
2 ``gitosis`` -- software for hosting ``git`` repositories
3 ==========================================================
5 Manage ``git`` repositories, provide access to them over SSH,
6 with tight access control and not needing shell accounts.
10 Documentation is still lacking, and non-default configurations
11 (e.g. config file, repositories, installing in a location that
12 is not in ``PATH``) basically have not been tested at all.
13 Basic usage should be very reliable -- the project has been
14 hosting itself for a long time. Any help is welcome.
16 ``gitosis`` aims to make hosting ``git`` repos easier and safer. It
17 manages multiple repositories under one user account, using SSH keys
18 to identify users. End users do not need shell accounts on the server,
19 they will talk to one shared account that will not let them run
22 ``gitosis`` is licensed under the GPL, see the file ``COPYING`` for
25 You can get ``gitosis`` via ``git`` by saying::
27 git clone git://eagain.net/gitosis
31 python setup.py install
33 Though you may want to use e.g. ``--prefix=``. For Debian/Ubuntu
34 users, the source is debianized.
40 First, we will create the user that will own the repositories. This is
41 usually called ``git``, but any name will work, and you can have more
42 than one per system if you really want to. The user does not need a
43 password, but does need a valid shell (otherwise, SSH will refuse to
46 I usually store ``git`` repositories in the subtree
47 ``/srv/example.com/git`` (replace ``example.com`` with your own
48 domain). You may choose another location. Adjust to suit and run::
53 --gecos 'git version control' \
56 --home /srv/example.com/git \
59 This command is known to work in Debian and Ubuntu. Your mileage may
62 You will need an SSH public key to continue. If you don't have one,
63 you need to generate one. See the man page for ``ssh-keygen``, and you
64 may also be interested in ``ssh-agent``. Create it on your personal
65 computer, and protect the *private* key well -- that includes not
66 transferring it over the network.
68 Next, we need to set things up for this newly-created user. The
69 following command will create a ``~/repositories`` that will hold the
70 ``git`` repositories, a ``~/.gitosis.conf`` that will be a symlink to
71 the actual configuration file, and it will add the SSH public key to
72 ``~/.ssh/authorized_keys`` with a ``command=`` option that restricts
73 it to running ``gitosis-serve``. Run::
75 sudo -H -u git gitosis-init <FILENAME.pub
76 # (or just copy-paste the public key when prompted)
78 then just ``git clone git@SERVER:gitosis-admin.git``, and you get a
79 repository with SSH keys as ``keys/USER.pub`` and a ``gitosis.conf``
80 where you can configure who has access to what.
84 For now, ``gitosis`` uses the ``HOME`` environment variable to
85 locate where to write its files. If you use ``sudo -u``
86 without ``-H``, ``sudo`` will leave the old value of ``HOME``
87 in place, and this will cause trouble. There will be a
88 workaround for that later on, but for now, always remember to
89 use ``-H`` if you're sudoing to the account.
91 You should always edit the configuration file via ``git``. The file
92 symlinked to ``~/.gitosis.conf`` on the server will be overwritten
93 when pushing changes to the ``gitosis-admin.git`` repository.
95 Edit the settings as you wish, commit and push. That's pretty much it!
96 Once you push, ``gitosis`` will immediately make your changes take
105 - add a ``keys/USER.pub`` file
106 - authorize them to read/write repositories as needed (or just
107 authorize the group ``@all``)
109 To create new repositories, just authorize writing to them and
110 push. It's that simple! For example: let's assume your username is
111 ``jdoe`` and you want to create a repository ``myproject``.
112 In your clone of ``gitosis-admin``, edit ``gitosis.conf`` and add::
118 Commit that change and push. Then create the initial commit and push
123 git remote add myserver git@MYSERVER:myproject.git
124 # do some work, git add and commit files
125 git push myserver master:refs/heads/master
127 That's it. If you now add others to ``members``, they can use that
131 Example configuration
132 =====================
134 .. include:: example.conf
141 You can email the author at ``tv@eagain.net``, or hop on
142 ``irc.freenode.net`` channel ``#git`` and hope for the best.
144 There will be more, keep an eye on http://eagain.net/ and/or the git