Git and Virtualmin

Introduction to Git
---------------------

Git is a source-code control system that allows multiple developers to work on the same project. Each developer has a copy of the repository on his workstation, and can check in changes to that repository and synchronize it with a central server. Other developers can then fetch those changes by synchronizing their local repository with the central one.

This documentation assumes that you already have a basic understanding of Git and source code control systems. Rather than explaining how Git works, it focuses on setting up repositories using Virtualmin.

Enabling the Git Plugin
-------------------------

Before you can use Git with Virtualmin, you must first enable the plugin at *System Settings* -> *Features and Plugins*. Just check the box next to *Git repositories* , then click the *Save* button. If this plugin does not appear, you may need to first install it. On a Redhat, Fedora or CentOS system, this is easiest done with the following commands, run as `root` :

On CentOS or RHEL, the install command is :

yum install wbm-virtualmin-git

on Debian or Ubuntu, the command is :

apt-get install webmin-virtualmin-git

If activating the plugin fails due to Git not being installed on your Virtualmin system, you will need to install it first. On Redhat, Fedora or CentOS the commands for this are :


rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm
yum install git gitweb
sed -e 's/^/#/' -i /etc/httpd/conf.d/git.conf
apachectl graceful

while on Debian or Ubuntu, the command is :

apt-get install git gitweb

If neither of those work, you can install the plugin from a Webmin module package as follows :

1. Go to Webmin -> Webmin Configuration -> Webmin Modules.
2. In the *From ftp or http URL* field, enter the URL http://download.webmin.com/download/plugins/virtualmin-git.wbm.gz
3. Click the *Install Module* button.

Once the plugin is installed, you can enable it in Virtualmin as follows :

1. Go to System Settings -> Features and Plugins.
2. Check the box in the left hand column next to *Git repositories*
3. Click *Save*.

Enabling Git For A Domain
----------------------------

Once the plugin is installed, you can allow a virtual server to create Git repositories as follows :

1. Select the domain from the left menu, and click *Edit Virtual Server*
2. In the *Enabled features* section check the box next to *Allow Git repositories?*
3. Click *Save Virtual Server*

This will perform the setup needed for repositories to be accessed under the `/git` URL path on this domain, but will not yet create any Git repositories.

Creating A Git Repository
---------------------------

Once a domain has Git enabled, you can add a repository to it like so :

1. Select the domain from the left menu, then open the *Services* category and click *Git Repositories*
2. In the *Create Git Repository* form, enter a name like `myproject` into the *Repository name* field.
3. Enter something like `My cool program` into the *Repository description* field.
4. Select at least one existing user in the domain to have access to the new repository in the *Grant access to users* field.
5. Click the *Create* button.

Once this is done your new repository will appear in the list on the *Git Repositories* page. It can then be accessed using the Git client with a URL like `http://yourdomain.com/git/myproject.git` . For more information on exactly which commands to use, click the *Repository Commands* button.

Granting Access To A Repository
---------------------------

All Git repositories created using Virtualmin allow write access only to authenticated users. Accounts can be created in the same way that you would create mailbox or FTP users, and existing users can be granted access to Git repositories.

When creating or editing a user, the *Other user permissions* section of the *Edit Mailbox* page will have a field named *Git login enabled?*. Just select *Yes*, and in the *Read/write access to repositories* field select one or more repos to grant full access to. As soon as the user is saved or created his login and password will be able to checkin to and checkout from the selected repositories.

When logging in you only need to use the user's short username, which is the part to the left of the `@` in his email address. For example, if the address was `bob@webmin.com` he would be able to login to Git as just `bob` , even though his IMAP and FTP is `bob-webmin`.

Managing Repositories
-------------------

Once a repository has been created you can manage it using buttons on the *Git Repositories* page. These are :

* *Delete*
Removes the repository, including all files within it and all user permissions.
* *Browse Repository*
Allows the contents and checkins to be navigated using a browser. This page is password-protected, but you can login using any access that has been granted Git access.
* *Repository Commands*
Shows example commands for pulling from and pushing to the repository.