How to setup Gitolite and Cgit on CentOS 6

This posting describes howto setup Gitolite3 and Cgit on CentOS 6. Please be aware that Gitolite3 uses ssh public key authentication. If you don’t know what that is or how to set it up then it’s probably better to first read up on that subject.

Setup
For the Gitolite3 server I’ll be using a KVM virtual machine with CentOS 6.4 x86_64. I guess you could use something else like Fedora assuming that the proper packages are all available. I’ll also be interacting with the Gitolite3 server from my workstation. Both are clearly visible in the prompt. If something is done as user patrick on the Gitolite3 server you will see [patrick@gitolite3-server ~]$ or as root [root@gitolite3-server ~]# and if something is done on my workstation as user patrick then you will see [patrick@workstation ~]$ or as root [root@workstation ~]#. Finally it’s possible to SSH from your workstation to the Gitolite3 server.

Let’s get started.

Step 1 – On the Gitolite3-server install the required packages

On the Gitolite3 server make sure that the EPEL repo is enabled or have the following RPMs in a local repo: Gitolite3 cgit git highlight policycoreutils-python

Add user ‘git’ if it does not exist on the Gitolite3 server and make sure it also belongs to the Gitolite3 group:

Step 2 – On the workstation create an SSH key for the Gitolite3 admin user

Now let’s create an SSH key for the person that will be the administrator of this Gitolite3 instance. In my case that user is patrick.

Important: you can *not* use the same key to access the Gitolite3-server via regular ssh and for accessing the Gitolite3 service. You *must* use separate keys.

Copy the Patrick-Gitolite3.pub public key to Gitolite3 server:

On the Gitolite3 server move the Patrick-Gitolite3.pub public key to /home/git/ and make sure that fileownership and filemode bits are set properly:

Step 3 – On the Gitolite3-server setup Gitolite3

On the Gitolite3 server as user git create a symlink to the public key and make sure the name of the symlink is the username you will use to git clone and git push to the Gitolite3 server. Usually that is the same username you use to login to your workstation.

Now setup Gitolite3:

If you don’t see any errors then you are done setting up Gitolite3. A couple of warnings about adding files are ok.

Step 4 – On the Gitolite3-server configure Gitolite3

Edit /home/git/.gitolite.rc and make the following changes:

Make sure that the permissions on /home/git/repositories/ are set correctly:

Step 5 – On the Gitolite3-server check sshd and iptables config

If you are using AllowUsers in your sshd config then make sure that the user git is allowed to login via ssh:

Also make sure that your firewall has port 22 open for ssh access.

Step 6 – On the workstation test Gitolite3 access

Let’s see if we can access Gitolite3 on the Gitolite3-server from the workstation. I am logged in as user patrick, I have my Patrick-Gitolite.pub public key and Patrick-Gitolite3 private key in /home/patrick/.ssh and then try to ssh to git@gitolite3-server using those keys as my identity:

If you see a similar message, congrats, your Gitolite3 setup works :-)

Step 7 – On the workstation clone gitolite-admin and add users & repos

Make sure you have git installed:

Create a directory where you will have or already have your Git repositories:

And clone the gitolite-admin repository:

Now let’s add an admin group, add user patrick to the admin group, add some metadata to the repos and add a repo for user patrick. The config changes below are just an example of the vast possibilities. Check the Gitolite3 docs how to make best use of the possibilities.

When done, commit the changes and push the changes back to the Gitolite3 server:

or if you use tags:

Step 8 – On the workstation add another user to have access to Gitolite3

There is a difference between allowing someone to access the Gitolite3-server via ssh and allowing someone access to the Gitolite3 *service* (not server but service) on the Gitolite3-server. They are not the same and are separate roles.

Secondly, it’s important to understand that in Gitolite3 the name of the public key of a user which is allowed access to the git repos controlled by Gitolite3 is tied to the actual username which ssh sends along to the Gitolite3 server when that user tries to access a git repo on the Gitolite3 server. This is usually the same username used to login to the workstation. When you create a new ssh key for a new user who needs access to the Gitolite3 service on the the Gitolite3-server you can name that public/private key anything you like but when you copy the public key to gitolite3-admin/keydir/ then the name of the public key must match the username that is used to access the Gitolite3 service on the Gitolite3-server.

You can *not* use the same key to access the Gitolite3-server via regular ssh and for accessing the Gitolite3 service. You *must* use separate keys.

Here is an example:

This results in:

Once John has generated his Gitolite3 key he sends ScoobyDoo-Gitolite3.pub to the Gitolite3 admin (aka patrick) who then copies ScoobyDoo-Gitolite3.pub to /home/patrick/Work/Git/gitolite3-admin/keydir/ on his workstation while making sure that the public key’s name matches the username that John uses to access the repos controlled by Gitolite3. Since that is the same as his login name ‘john’ the public key should be called ‘john.pub’.

An alternative which I have not tested may be to put the original keys (like ScoobyDoo-Gitolite3.pub) in a separate directory gitolite-admin/original_keys/ and use a symlink (in this case john.pub) which makes it easier to keep track of the keys.

Once the key is added to gitolite-admin/keydir and user john has been granted access to one or more repos on gitolite-admin/conf/gitolite.conf then it’s just a matter of:

or if you use tags:

Step 9 – On the Gitolite3-server setup cgit

Install cgit and deps:

Set filemode of git’s homedir so Apache can traverse:

Set filemode of projects.list so Apache can read it:

Set proper SELinux labels on the project.list and repositories:

On RHEL 6.4 or CentOS 6.4 and earlier use:

On RHEL 6.5 or CentOS 6.5 use:

Fix the SELinux labels:

Restore the proper SELinux labels in /home/git:

Make sure that restorecon resets the SELinux labels of projects.list and repositories/ to the proper ones if they get rewritten on a git push:

Make sure that the restorecond service is enabled and active:

Add option to highlight:

Use this cgit configuration in /etc/cgitrc:

Make sure that the httpd service is enabled and active:

Finally make sure that your firewall has port 80 open for web access to cgit.

Tip for Gitolite3 admins

Here’s an optional concept that you can use to distinguish ssh’ing into the Gitolite3-server and accessing the repos controlled by the Gitolite3 service.

Add an ssh config file with both types of connections. Please note that “Host” used in this config file is *not* a DNS name. You can use anything you want. Hostname on the other hand must be the IP address, hostname or FQDN of the Gitolite3-server.

Notice the different IdentityFile and User entries?

The first entry can be used like this:

Which means it does this:

The second entry can be used like this:

Which means it does this:

Comments and enhancements always welcome.