https://wiki.archlinux.org/api.php?action=feedcontributions&user=A.J.Rouvoet&feedformat=atomArchWiki - User contributions [en]2024-03-29T00:20:03ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Gitosis&diff=225594Gitosis2012-09-27T10:21:45Z<p>A.J.Rouvoet: /* Installation and setup */</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Daemons and system services]]<br />
[[Category:Secure Shell]]<br />
[[tr:Gitosis]]<br />
{{poor writing}}<br />
<br />
Gitosis is a tool which provides access control and remote management for hosted [[Git]] repositories. It allows for fine-grained management of read and write access over SSH, without requiring that the users have local system accounts on the server. To do this, it sets up a single system account "{{ic|git}}" which is then used for all Git access.<br />
<br />
Gitosis provides installation instructions in its [http://eagain.net/gitweb/?p=gitosis.git;a=blob;f=README.rst;hb=HEAD README] file. This guide is based on those instructions.<br />
<br />
== Installation and setup ==<br />
<br />
Install the [https://aur.archlinux.org/packages.php?ID=23419 gitosis-git] package from the [[AUR]]. This will create three things:<br />
* the {{ic|git}} user<br />
* the {{ic|git}} group to which this user belongs<br />
* the {{ic|/srv/gitosis}} directory, which will hold data and repositories for Gitosis<br />
<br />
To configure Gitosis, you do not edit files directly on the server. Instead, Gitosis provides a Git repository which contains the configuration. To update this configuration, you clone, commit, and push to {{ic|gitosis-admin}} just as you would any other repository.<br />
<br />
Since Gitosis uses [[SSH keys]] to authenticate users, you will need to generate a keypair to use for the administrative repository. If you do not have one, you can generate it using {{ic|ssh-keygen}}, for example:<br />
$ ssh-keygen -t rsa<br />
<br />
You can now initialize the administrative repository.<br />
<br />
$ sudo -H -u git gitosis-init < /path/to/public_key.pub<br />
Initialized empty Git repository in /srv/gitosis/repositories/gitosis-admin.git/<br />
Reinitialized existing Git repository in /srv/gitosis/repositories/gitosis-admin.git/<br />
<br />
{{<br />
note|In some cases, this might result in an error of this kind:<br />
<br />
OSError: [Errno 13] Permission denied: '//gitosis'<br />
<br />
The cause of this might be that the git home directory was not set properly.<br />
Fix it by setting it manally:<br />
<br />
# usermod -d /srv/gitosis git<br />
}}<br />
<br />
In addition, this command creates the directory {{ic|/srv/gitosis/repositories}} in which the actual hosted repositories will be stored.<br />
<br />
After the initialisation of the admin repository is complete, it might be sensible to disable the password based ssh login of the user git.<br />
<br />
To achieve this, add<br />
Match User git<br />
PasswordAuthentication no<br />
<br />
at the end of {{ic|/etc/ssh/sshd_config}}<br />
<br />
== Configuration ==<br />
<br />
As mentioned above, Gitosis is configured by pushing commits to the {{ic|gitosis-admin}} repository. To clone this repository (using Gitosis!), run:<br />
<br />
$ git clone git@your.git.server:gitosis-admin.git<br />
<br />
Inside the {{ic|gitosis-admin}} repository, you will see two things:<br />
* {{ic|gitosis.conf}} &ndash; configuration file for Gitosis and repository permissions<br />
* {{ic|keydir}} &ndash; directory containing public keys for each user<br />
<br />
To modify repositories or users, or to configure Gitosis, just commit changes in your clone and push them back to the server.<br />
<br />
=== Repositories and permissions ===<br />
<br />
You'll be able to find some example configuration files in ''/usr/share/doc/gitosis''.<br />
<br />
[gitosis]<br />
gitweb = yes<br />
<br />
[repo foobar]<br />
description = Git repository for foobar<br />
owner = user<br />
<br />
[group devs]<br />
members = user1 user2<br />
<br />
[group admins]<br />
members = user1<br />
<br />
[group gitosis-admin]<br />
writable = gitosis-admin<br />
members = @admins<br />
<br />
[group foobar]<br />
writable = foobar<br />
members = @devs<br />
<br />
[group myteam]<br />
writable = free_monkey<br />
members = jdoe<br />
<br />
This defines a new group called "free_monkey", which is an arbitrary string. "jdoe" is a member of myteam and will have write access to the "gitosis" repository.<br />
<br />
Save this addition to gitosis.conf, commit and push it: <br />
<br />
$ git commit -a -m "Allow jdoe write access to free_monkey"<br />
$ git push<br />
<br />
Now the user "jdoe" has access to write to the repository named "free_monkey", but we still have not created a repository yet. What we will do is create a new repository locally, initialize it on the Git server, and then push it: <br />
<br />
$ mkdir free_monkey<br />
$ cd free_monkey<br />
$ git init<br />
$ git remote add origin git@YOUR_SERVER_HOSTNAME:free_monkey.git<br />
<br />
Do some work, git add and commit files<br />
<br />
$ git push origin master:refs/heads/master<br />
<br />
When using SSH, the last command will fail with the error message "does not appear to be a Git repository"<br />
This can be fixed by initializing the repository manually on the server<br />
$ git init --bare /srv/gitosis/repositories/free_monkey.git<br />
<br />
and retry the last command<br />
<br />
With the final push, you are off to the races. The repository "free_monkey" has been created on the server (in /srv/gitosis/repositories) and you are ready to start using it like any ol' Git repository. <br />
<br />
Gitosis repositories can also be used with gitweb; just point the directory that contains the repository inside the gitweb configuration.<br />
<br />
=== Adding users ===<br />
<br />
The next natural thing to do is to grant a lucky few commit access to the FreeMonkey project. This is a simple two step process.<br />
<br />
First, gather their public SSH keys, which I'll call "alice.pub" and "bob.pub", and drop them into keydir/ of your local gitosis-admin repository. Second, edit gitosis.conf and add them to the "members" list.<br />
<br />
$ cd gitosis-admin<br />
$ cp ~/alice.pub keydir/<br />
$ cp ~/bob.pub keydir/<br />
$ git add keydir/alice.pub keydir/bob.pub<br />
<br />
Note that the key filename must have a ".pub" extension.<br />
<br />
gitosis.conf changes:<br />
<br />
[group myteam]<br />
members = jdoe alice bob<br />
writable = free_monkey<br />
<br />
Commit and push:<br />
<br />
$ git commit -a -m "Granted Alice and Bob commit rights to FreeMonkey"<br />
$ git push<br />
<br />
That's it. Alice and Bob can now clone the free_monkey repository like so:<br />
<br />
$ git clone git@YOUR_SERVER_HOSTNAME:free_monkey.git<br />
<br />
Alice and Bob will also have commit rights.<br />
<br />
=== Public access ===<br />
<br />
If you are running a public project, you will have your users with commit rights, and then you'll have everyone else. How do we give everyone else read-only access without fiddling with SSH keys?<br />
<br />
We just use git-daemon. This is independent of Gitosis and it comes with Git itself.<br />
<br />
$ sudo -u git git-daemon --base-path=/srv/gitosis/repositories/ --export-all<br />
<br />
This will make all the repositories you manage with Gitosis read-only for the public. Someone can then clone FreeMonkey like so:<br />
<br />
$ git clone git://YOUR_SERVER_HOSTNAME/free_monkey.git<br />
<br />
To export only some repositories and not others, you need to touch git-daemon-export-ok inside the root directory (e.g. /srv/gitosis/repositories/free_monkey.git) of each repository that you want public. Then remove "--export-all" from the git-daemon command above.<br />
<br />
=== More tricks ===<br />
<br />
gitosis.conf can be set to do some other neat tricks. Open example.conf in the Gitosis source directory (where you originally cloned Gitosis way at the top) to see a summary of all options. You can specify some repositories to be read-only (opposite of writable), but yet not public. A group members list can include another group. And a few other tricks that I'll leave it to the reader to discover.<br />
<br />
Caveats<br />
<br />
If /srv/gitosis/.gitosis.conf on your server never seems to get updated to match your local copy (they should match), even though you are making changes and pushing, it could be that your post-update hook is not executable. Older versions of setuptools can cause this. Be sure to fix that:<br />
<br />
$ sudo chmod 755 /srv/gitosis/repositories/gitosis-admin.git/hooks/post-update<br />
<br />
If your Python goodies are in a non-standard location, you must additionally edit post-update and put an "export PYTHONPATH=..." line at the top. Failure to do so will give you a Python stack trace the first time you try to push changes within gitosis-admin.<br />
<br />
If you want to install Gitosis in a non-standard location, I do not recommend it. It's an edge case that the author has not run up against until I bugged him to help me get it working.<br />
<br />
For the brave, you need to edit whatever file on your system controls the default PATH for a non-login, non-interactive shell. On Ubuntu this is /etc/environment. Add the path to gitosis-serve to the PATH line. Also insert a line for PYTHONPATH and set it to your non-standard Python site-packages directory. As an example, this is my /etc/environment:<br />
<br />
$ PATH="/home/$(whoami)/sys/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games"<br />
$ PYTHONPATH=/home/$(whoami)/sys/lib/python2.4/site-packages<br />
<br />
Be sure to logout and log back in after you make these changes.<br />
<br />
Do not use the gitosis-init line I have above for the standard install, instead use this slightly modified one:<br />
<br />
$ sudo -H -u git env PATH=$PATH gitosis-init < /tmp/id_rsa.pub<br />
<br />
Be sure to also set PYTHONPATH in your post-update hook as described above.<br />
<br />
That *should* do it. I am purposefully terse with this non-standard setup as I think not many people will use it. Hit me up in #git on FreeNode if you need more information (my nick is up_the_irons).<br />
<br />
=== Non-standard SSH port ===<br />
<br />
If you run SSH on a non-standard port on your server, there are two ways of specifying on which port Git will try to connect. One is to explicitly state that you are using the SSH protocol, as this lets you put<br />
in a port number in the URL too:<br />
<br />
git clone ssh://git@myserver.com:1234/repo.git<br />
<br />
Or you can put this in your ~/.ssh/config file:<br />
<br />
$ Host myserver.com<br />
$ Port 1234<br />
<br />
* [repo] blocks are used to define some necessary areas being used with gitweb.<br />
* [group] blocks are used for both:<br />
** defining user groups<br />
** defining repository permissions<br />
* @ is used to define user groups.<br />
<br />
You should commit and push any changes you do in this file.<br />
<br />
=== keydir ===<br />
<br />
keydir is simply a directory that contains public keys of the users. Some of the keys can be in the form of user@machine and those keys must be defined with that form inside gitosis.conf. It's better to create user groups and use them as members of the repositories. Once you add new keys to enable some new users, you should add the files to the Git repository and commit and push them. The new users will use the above form of Git commands like you have used to clone the gitosis-admin repository.<br />
<br />
== See also ==<br />
* [http://eagain.net/gitweb/?p=gitosis.git Gitosis source]<br />
* [[Gitolite]] &ndash; an alternative to Gitosis which provides many similar features<br />
* [http://repo.or.cz/w/girocco.git Girocco] &ndash; Git hosting code used on repo.or.cz<br />
* [http://gitorious.org/gitorious/pages/Home Gitorious] &ndash; open-source Git hosting<br />
* [[Gitlab]] &ndash; a free git repository management application based on Ruby on Rails and Gitolite.</div>A.J.Rouvoethttps://wiki.archlinux.org/index.php?title=Gitosis&diff=225590Gitosis2012-09-27T10:14:28Z<p>A.J.Rouvoet: /* Installation and setup */</p>
<hr />
<div>[[Category:Version Control System]]<br />
[[Category:Daemons and system services]]<br />
[[Category:Secure Shell]]<br />
[[tr:Gitosis]]<br />
{{poor writing}}<br />
<br />
Gitosis is a tool which provides access control and remote management for hosted [[Git]] repositories. It allows for fine-grained management of read and write access over SSH, without requiring that the users have local system accounts on the server. To do this, it sets up a single system account "{{ic|git}}" which is then used for all Git access.<br />
<br />
Gitosis provides installation instructions in its [http://eagain.net/gitweb/?p=gitosis.git;a=blob;f=README.rst;hb=HEAD README] file. This guide is based on those instructions.<br />
<br />
== Installation and setup ==<br />
<br />
Install the [https://aur.archlinux.org/packages.php?ID=23419 gitosis-git] package from the [[AUR]]. This will create three things:<br />
* the {{ic|git}} user<br />
* the {{ic|git}} group to which this user belongs<br />
* the {{ic|/srv/gitosis}} directory, which will hold data and repositories for Gitosis<br />
<br />
To configure Gitosis, you do not edit files directly on the server. Instead, Gitosis provides a Git repository which contains the configuration. To update this configuration, you clone, commit, and push to {{ic|gitosis-admin}} just as you would any other repository.<br />
<br />
Since Gitosis uses [[SSH keys]] to authenticate users, you will need to generate a keypair to use for the administrative repository. If you do not have one, you can generate it using {{ic|ssh-keygen}}, for example:<br />
$ ssh-keygen -t rsa<br />
<br />
You can now initialize the administrative repository.<br />
<br />
$ sudo -H -u git gitosis-init < /path/to/public_key.pub<br />
Initialized empty Git repository in /srv/gitosis/repositories/gitosis-admin.git/<br />
Reinitialized existing Git repository in /srv/gitosis/repositories/gitosis-admin.git/<br />
<br />
{{<br />
note|In some cases, this might result in an error of this kind:<br />
<br />
OSError: [Errno 13] Permission denied: '//gitosis'<br />
<br />
The cause of this might be that the git home directory was not created.<br />
If that is indeed the case: create it manually, chown it `git:git` and try again.<br />
<br />
$ sudo mkdir /home/git<br />
$ sudo chown git:git /home/git<br />
$ sudo usermod -d /home/git git<br />
}}<br />
<br />
In addition, this command creates the directory {{ic|/srv/gitosis/repositories}} in which the actual hosted repositories will be stored.<br />
<br />
After the initialisation of the admin repository is complete, it might be sensible to disable the password based ssh login of the user git.<br />
<br />
To achieve this, add<br />
Match User git<br />
PasswordAuthentication no<br />
<br />
at the end of {{ic|/etc/ssh/sshd_config}}<br />
<br />
== Configuration ==<br />
<br />
As mentioned above, Gitosis is configured by pushing commits to the {{ic|gitosis-admin}} repository. To clone this repository (using Gitosis!), run:<br />
<br />
$ git clone git@your.git.server:gitosis-admin.git<br />
<br />
Inside the {{ic|gitosis-admin}} repository, you will see two things:<br />
* {{ic|gitosis.conf}} &ndash; configuration file for Gitosis and repository permissions<br />
* {{ic|keydir}} &ndash; directory containing public keys for each user<br />
<br />
To modify repositories or users, or to configure Gitosis, just commit changes in your clone and push them back to the server.<br />
<br />
=== Repositories and permissions ===<br />
<br />
You'll be able to find some example configuration files in ''/usr/share/doc/gitosis''.<br />
<br />
[gitosis]<br />
gitweb = yes<br />
<br />
[repo foobar]<br />
description = Git repository for foobar<br />
owner = user<br />
<br />
[group devs]<br />
members = user1 user2<br />
<br />
[group admins]<br />
members = user1<br />
<br />
[group gitosis-admin]<br />
writable = gitosis-admin<br />
members = @admins<br />
<br />
[group foobar]<br />
writable = foobar<br />
members = @devs<br />
<br />
[group myteam]<br />
writable = free_monkey<br />
members = jdoe<br />
<br />
This defines a new group called "free_monkey", which is an arbitrary string. "jdoe" is a member of myteam and will have write access to the "gitosis" repository.<br />
<br />
Save this addition to gitosis.conf, commit and push it: <br />
<br />
$ git commit -a -m "Allow jdoe write access to free_monkey"<br />
$ git push<br />
<br />
Now the user "jdoe" has access to write to the repository named "free_monkey", but we still have not created a repository yet. What we will do is create a new repository locally, initialize it on the Git server, and then push it: <br />
<br />
$ mkdir free_monkey<br />
$ cd free_monkey<br />
$ git init<br />
$ git remote add origin git@YOUR_SERVER_HOSTNAME:free_monkey.git<br />
<br />
Do some work, git add and commit files<br />
<br />
$ git push origin master:refs/heads/master<br />
<br />
When using SSH, the last command will fail with the error message "does not appear to be a Git repository"<br />
This can be fixed by initializing the repository manually on the server<br />
$ git init --bare /srv/gitosis/repositories/free_monkey.git<br />
<br />
and retry the last command<br />
<br />
With the final push, you are off to the races. The repository "free_monkey" has been created on the server (in /srv/gitosis/repositories) and you are ready to start using it like any ol' Git repository. <br />
<br />
Gitosis repositories can also be used with gitweb; just point the directory that contains the repository inside the gitweb configuration.<br />
<br />
=== Adding users ===<br />
<br />
The next natural thing to do is to grant a lucky few commit access to the FreeMonkey project. This is a simple two step process.<br />
<br />
First, gather their public SSH keys, which I'll call "alice.pub" and "bob.pub", and drop them into keydir/ of your local gitosis-admin repository. Second, edit gitosis.conf and add them to the "members" list.<br />
<br />
$ cd gitosis-admin<br />
$ cp ~/alice.pub keydir/<br />
$ cp ~/bob.pub keydir/<br />
$ git add keydir/alice.pub keydir/bob.pub<br />
<br />
Note that the key filename must have a ".pub" extension.<br />
<br />
gitosis.conf changes:<br />
<br />
[group myteam]<br />
members = jdoe alice bob<br />
writable = free_monkey<br />
<br />
Commit and push:<br />
<br />
$ git commit -a -m "Granted Alice and Bob commit rights to FreeMonkey"<br />
$ git push<br />
<br />
That's it. Alice and Bob can now clone the free_monkey repository like so:<br />
<br />
$ git clone git@YOUR_SERVER_HOSTNAME:free_monkey.git<br />
<br />
Alice and Bob will also have commit rights.<br />
<br />
=== Public access ===<br />
<br />
If you are running a public project, you will have your users with commit rights, and then you'll have everyone else. How do we give everyone else read-only access without fiddling with SSH keys?<br />
<br />
We just use git-daemon. This is independent of Gitosis and it comes with Git itself.<br />
<br />
$ sudo -u git git-daemon --base-path=/srv/gitosis/repositories/ --export-all<br />
<br />
This will make all the repositories you manage with Gitosis read-only for the public. Someone can then clone FreeMonkey like so:<br />
<br />
$ git clone git://YOUR_SERVER_HOSTNAME/free_monkey.git<br />
<br />
To export only some repositories and not others, you need to touch git-daemon-export-ok inside the root directory (e.g. /srv/gitosis/repositories/free_monkey.git) of each repository that you want public. Then remove "--export-all" from the git-daemon command above.<br />
<br />
=== More tricks ===<br />
<br />
gitosis.conf can be set to do some other neat tricks. Open example.conf in the Gitosis source directory (where you originally cloned Gitosis way at the top) to see a summary of all options. You can specify some repositories to be read-only (opposite of writable), but yet not public. A group members list can include another group. And a few other tricks that I'll leave it to the reader to discover.<br />
<br />
Caveats<br />
<br />
If /srv/gitosis/.gitosis.conf on your server never seems to get updated to match your local copy (they should match), even though you are making changes and pushing, it could be that your post-update hook is not executable. Older versions of setuptools can cause this. Be sure to fix that:<br />
<br />
$ sudo chmod 755 /srv/gitosis/repositories/gitosis-admin.git/hooks/post-update<br />
<br />
If your Python goodies are in a non-standard location, you must additionally edit post-update and put an "export PYTHONPATH=..." line at the top. Failure to do so will give you a Python stack trace the first time you try to push changes within gitosis-admin.<br />
<br />
If you want to install Gitosis in a non-standard location, I do not recommend it. It's an edge case that the author has not run up against until I bugged him to help me get it working.<br />
<br />
For the brave, you need to edit whatever file on your system controls the default PATH for a non-login, non-interactive shell. On Ubuntu this is /etc/environment. Add the path to gitosis-serve to the PATH line. Also insert a line for PYTHONPATH and set it to your non-standard Python site-packages directory. As an example, this is my /etc/environment:<br />
<br />
$ PATH="/home/$(whoami)/sys/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games"<br />
$ PYTHONPATH=/home/$(whoami)/sys/lib/python2.4/site-packages<br />
<br />
Be sure to logout and log back in after you make these changes.<br />
<br />
Do not use the gitosis-init line I have above for the standard install, instead use this slightly modified one:<br />
<br />
$ sudo -H -u git env PATH=$PATH gitosis-init < /tmp/id_rsa.pub<br />
<br />
Be sure to also set PYTHONPATH in your post-update hook as described above.<br />
<br />
That *should* do it. I am purposefully terse with this non-standard setup as I think not many people will use it. Hit me up in #git on FreeNode if you need more information (my nick is up_the_irons).<br />
<br />
=== Non-standard SSH port ===<br />
<br />
If you run SSH on a non-standard port on your server, there are two ways of specifying on which port Git will try to connect. One is to explicitly state that you are using the SSH protocol, as this lets you put<br />
in a port number in the URL too:<br />
<br />
git clone ssh://git@myserver.com:1234/repo.git<br />
<br />
Or you can put this in your ~/.ssh/config file:<br />
<br />
$ Host myserver.com<br />
$ Port 1234<br />
<br />
* [repo] blocks are used to define some necessary areas being used with gitweb.<br />
* [group] blocks are used for both:<br />
** defining user groups<br />
** defining repository permissions<br />
* @ is used to define user groups.<br />
<br />
You should commit and push any changes you do in this file.<br />
<br />
=== keydir ===<br />
<br />
keydir is simply a directory that contains public keys of the users. Some of the keys can be in the form of user@machine and those keys must be defined with that form inside gitosis.conf. It's better to create user groups and use them as members of the repositories. Once you add new keys to enable some new users, you should add the files to the Git repository and commit and push them. The new users will use the above form of Git commands like you have used to clone the gitosis-admin repository.<br />
<br />
== See also ==<br />
* [http://eagain.net/gitweb/?p=gitosis.git Gitosis source]<br />
* [[Gitolite]] &ndash; an alternative to Gitosis which provides many similar features<br />
* [http://repo.or.cz/w/girocco.git Girocco] &ndash; Git hosting code used on repo.or.cz<br />
* [http://gitorious.org/gitorious/pages/Home Gitorious] &ndash; open-source Git hosting<br />
* [[Gitlab]] &ndash; a free git repository management application based on Ruby on Rails and Gitolite.</div>A.J.Rouvoet