WANdisco Git MultiSite logo

7.Gitolite Integration Guide

7.1 Running Git MultiSite with Gitolite


From Git MultiSite 1.3 onwards, it is possible to run and replicate Gitolite, the popular authorization layer.

Authentication vs Authorization

Authorization is about deciding what users are allowed to do on a system. It is distinct from and follows on from the authentication, where users are identified.

Gitolites authorization rules are enforced based on the configuration of the gitolite.conf file within the gitolite-admin repository which is created during installation. Changes to this file are enforced once a push to this repo has been recieved via post-update hook within the repository.

As the rules are contained within a repository it is possible to install GitMS to replicate this repo to allow the same authorization to be applied across multiple nodes. Outlined below is the instructions for allowing GitMS to replicate Gitolite.

7.2 Requirements

 System setup

 Git MultiSite
You must be running Git MultiSite 1.3 or later. Earlier versions of Git MultSite did not support the replication of environmental variables

You need to have Git Replicated binaries installed on all nodes.

Use Oracle Java JRE-1.7 installed on all nodes.

VMs with a git user with no authorized keys file present or previous ssh configuration

Generate/copy over public SSH keys for the users you wish to use on Gitolite (must not be git users). We recommend simple naming on these files eg. admin.pub, generated by ssh-keygen. Do not set a passphrase.


If SELinux is installed, and wish to continue using it, there are two installion options for gitolite, either adding it to an already allowed directory such as /var/lib/gitolite or adding permissions to SELinux to allow the home directory of user git to be written to by httpd.

Below are the SELinux commands that need entered to allow gitolite over apache:

# yum -y install policycoreutils-python
# setsebool -P httpd_enable_homedirs on
# usermod -a -G apache git 
# chcon -R -t httpd_sys_rw_content_t /home/gitms
# chcon -R -t httpd_sys_rw_content_t /opt/wandisco/git-multisite/replicator/content_delivery  
# setsebool -P httpd_can_network_connect on                    
# setsebool -P git_system_enable_homedirs on 
# semanage permissive -a httpd_sys_script_t     

Configure IPtables

If IPtables is active it will block Http connections aswell as the gitms replicator/UI too allow these connections add the following exceptions to iptables: /etc/sysconfig/iptables should look like:

:OUTPUT ACCEPT [11:12222]
-A INPUT -p icmp -j ACCEPT
-A INPUT -i lo -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 6789 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 8080 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 80 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 8082 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 8085 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 9001 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 443 -j ACCEPT
-A INPUT -p tcp -m state --state NEW -m tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-host-prohibited
-A FORWARD -j REJECT --reject-with icmp-host-prohibited
# Completed on Mon Jul 29 13:52:30 2013	

Increased the OUTPUT ACCEPT from 2222 to 12222 (allows outgoing connections up to port 12222)

7.4 Deploy over SSH

Follow these steps if you plan to run Gitolite and Git MultiSite over SSH

  1. Start by logging into the git user in the home directory create a bin folder
  2. Add this folder to $PATH. By appending the below line to .bashrc or .bashrc_profile of git user
    # export PATH=$PATH:$HOME/bin
    May need to do "source .bashrc" or logout and back in to get changes to take effect " echo $PATH " should show your new bin folder at the end
  3. Scp the admin.pub key from the client machine to git users home directory on Gitolite server
  4. Get the Gitolite installation folder via Git with below command.
    # git clone git://github.com/sitaramc/gitolite
  5. As the git user run the following commands from home directory
    #  gitolite/install -ln
    #  gitolite setup -pk $HOME/admin.pub  ( or key of which ever user wish to make first admin )	
    Repeat this on Both nodes with the same admin.pub key , after the last step should have a repositories folder in home directory with two repos present, a gitolite-admin.git and testing.git To test that the setup is correct from client machine run this command as admin user :
    # git clone git@<serveraddress>:gitolite-admin
    Should be able to successfully clone out the gitolite-admin repo this repo will have a single commit in git logs for Gitolite setup
    #  cd gitolite-admin
    #  git log
    #  commit 21729090fb8c5cc55a6050f728a85b99f352e177
    #  Author: git on gitolite.domain <git@gitolite.domain>
    #  Date:   Wed Jul 30 08:40:10 2014 -0400
    #  gitolite setup -pk /home/git/admin.pub	
    From as this commit is different on each node we will need to get the repository in a consistent state this is done through ryncing the node between each server From /home/git/repositories run the following command:
    # rsync -r gitolite-admin.git root@<otherServerIP>:/home/git/repositories/gitolite-admin.git
    Then on other server change ownership of the repo to git:git
    # chown -R git:git gitolite-admin.git
    cd into the admin repo and check the git log again the commit message should match the other version of the gitolite-admin repo.

7.3 Installation and setup of GitMS

  1. Download and install preferred version of GitMS ( tarball or Rpm ) under the git user and git group
  2. Once Nodes are inducted to each other create a replication group including both nodes
  3. Add the gitolite-admin repo to the replication group.
  4. To allow for enforcement of access-control changes in Gitolite, the Gitolite environment variables must also be replicated.

Setting up GitMS to replicate Gitolite Variables

To allow GitMS to send the enviroment variables for gitolite across both servers the application.properties file must be updated there are 3 ways this is done listed below

Direct edit of application.properties file

  1. open the applications.properties file for GitMS in <gitms_installation_folder>/replicator/properties/application.properties (default install is /opt/wandisco/git-multisite/)
  2. append the following line to the bottom of the file on each server:
  3. following this restart the replicator for each node

Curl command sent to replicator

  1. Sending a curl command to the replicated settings endpoint will allow the changes to be replicated out to all members inducted to the node, which the command was sent to.
  2. Issue the following command via curl:
    # curl --header "Content-Type: application/xml" -X PUT -data @replicated_config.xml http://<ServerIP>:8082/api/configuration/replicated
    Where replicated_config.xml is a xml with the environmental variables to be replicated. As shown below:
    These settings will be passed out across all nodes this can be confirmed by checking the applications.properties file of each node.

Using replicated settings script

The below script can also be used to send settings out to all inducted nodes the usage of this script is as follows

# ./replicated_settings -a <Path_to_applications.properties> -k gitms.hooks.env -v GL_USER,GL_TID,GL_LOGFILE,GL_ADMIN_BASE,GL_REPO,GL_BINDIR,GL_LIBDIR
This should be run locally on one of Gitolite servers Link to script : replicated_settings.sh

Changes to gitolite-admin repo to allow replication

To allow the post-update scripts of gitolite to be run upon receipt of a replicated upgrade we need to edit the gitolite-admin repo.

  1. cd to the hooks folder of gitolite-admin.git repo should be in: $HOME/repositories/gitolite-admin.git/hooks.
  2. symlink the already present post-update script to rp-post-update with command below:
    # ln -s post-update rp-post-update
  3. Can either repeat this command in each version of the repository or rsync it to all other servers.
  4. Carrying out the "ls -l" command should show something similar to the below output:
    #   lrwxrwxrwx. 1 git  git  52 Jul 30 08:40 post-update -> /home/git/.gitolite/hooks/gitolite-admin/post-update
    #   lrwxrwxrwx. 1 git  git  11 Jul 30 11:23 rp-post-update -> post-update
    #   lrwxrwxrwx. 1 git  git  39 Jul 30 08:40 update -> /home/git/.gitolite/hooks/common/update
  5. Following this can clone the gitolite-admin repo using command below as admin user on client to begin configuring Gitolite: # git clone git@<server_address>:gitolite-admin
  6. Changes made should now be replicated and enforced by all instances of Gitolite in the replication-group.

Deploy over HTTP

Starting Requirements

This Section will start under the assumption that the previous steps to install and set up Gitolite and GitMS have been completed and working. Setup :

Install apache
# yum -y install httpd
install ssl support
# yum -y install httpd mod_ssl

Create passwd file

  1. htpasswd -c /var/www/gitolite.passwd <Username>
  2. Change the ownership of the passwd file:
    chown apache:apache /var/www/gitolite.passwd

Setting up Gitolite to authenticate over HTTP

  1. Start by editing the .gitolite.rc file, ( found in the gitolite installation directory: /home/git , in our example) add the following line to the top of the file:
    $ENV{PATH} .= ":/home/git/bin";
    replacing /home/git/bin with the bin directory of gitolite.
    create folders in the httpd home folder this will default to /var/www/ on centos and oracle linux
    # mkdir /var/www/git /var/www/bin
    correct the permissions and ownership of the new folders:
    # chown -R apache:apache /var/www/git
    # chown -R git:git /var/www/bin
    # chmod -R 0755 /var/www/git /var/www/bin
    In the /var/www/bin folder create "gitolite-suexec-wrapper" script and add the following lines :
    # Suexec wrapper for gitolite-shell
    export GIT_PROJECT_ROOT="/home/git/repositories"
    export GITOLITE_HTTP_HOME="/home/git"
    where GIT_PROJECT_ROOT is the repositories directory for gitolite and GITOLITE_HTTP_HOME is the directory that contains Gitolite Give this script the permissions 0700
    # chmod 0700 gitolite-suexec-wrapper
    # chown git:git gitolite-suexec-wrapper
    Next create conf file for gitolite, this will be under the /etc/httpd/conf.d folder create file gitolite.conf and add the following lines:
    <VirtualHost *:80>
        ServerName        git.example.com
        ServerAlias       git
        ServerAdmin       you@example.com
        DocumentRoot /var/www/git
        <Directory /var/www/git>
            Options       None
            AllowOverride none
            Order         allow,deny
            Allow         from all
        SuexecUserGroup git git
        ScriptAlias /git/ /var/www/bin/gitolite-suexec-wrapper/
        ScriptAlias /gitmob/ /var/www/bin/gitolite-suexec-wrapper/
        <Location /git>
            AuthType Basic
            AuthName "Git Access"
            Require valid-user
            AuthUserFile /var/www/gitolite.passwd

    Allow git pushes

    Change to the directory were the repo is

    su - gitms -s /bin/bash
    cd /home/gitms/repos/bar.git
    git config http.receivepack true
    git config core.sharedRepository group	

    This needs to be done in each repo and on all replicas. e.g. each version of repo1 on each node

    Following this Restart Apache

    # service httpd restart
    Should now be able to authenticate through Apache and apply authorization rules to users coming in over http

    7.6 Deploy over HTTPS

    To allow authentication of users over HTTPS begin by following the set up steps above for http.

    To this file add the following lines:

    Generate Certificates

    An easy tool to generate certificates is easy-rsa (http://openvpn.net/index.php/open-source/documentation/miscellaneous/77-rsa-key-management.html) You need to have the Epel rep installed to use this:

    # wget http://dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
    # rpm -Uvh epel-release-6-8.noarch.rpm
    # yum install easy-rsa
    # cp -r /usr/share/easy-rsa/2.0 .
    # cd 2.0/
    # source vars
    # ./clean-all
    # ./build-ca
    # ./build-key-server gitolite1 (when prompted for the CommonName use the system IP address if the system does not have a register DNS name)

    Copy a cert and key into /etc/apache on each node :

    # cp ./keys/gitolite1.crt /etc/httpd
    # cp ./keys/gitolite1.key /etc/httpd
    # chown apache:apache /etc/httpd/gitolite1.crt /etc/httpd/gitolite1.key	

    Add conf file for Https

    In the apache conf files add a conf file for Https in /etc/httpd/conf.d/gitolitehttps.conf

    to this file add the following lines:

    <VirtualHost *:443>
    DocumentRoot /var/www/git
    ServerName git.example.com
    RewriteEngine On
    RewriteCond %{REMOTE_USER} ^(.*)$
    RewriteRule ^(.*)$ - [E=R_U:%1]
    RequestHeader set X-Remote-User %{R_U}e
    SSLEngine on
    SSLCertificateFile /etc/httpd/gitolite1.crt
    SSLCertificateKeyFile /etc/httpd/gitolite1.key
     DocumentRoot /var/www/git
        <Directory /var/www/git>
            Options        +ExecCGI
            AllowOverride none
            Order         allow,deny
            Allow         from all
        SuexecUserGroup git git
        ScriptAlias /git/ /var/www/bin/gitolite-suexec-wrapper.sh/
        ScriptAlias /gitmob/ /var/www/bin/gitolite-suexec-wrapper.sh/
        <Location /git>
            AuthType Basic
            AuthName "Git Access"
            Require valid-user
            AuthUserFile /var/www/gitolite.passwd

    Following this restart Apache

    # service httpd restart

    Adding the certificate to client machines

    The server certificate generated will not be recognized by your client. You can either turn off strict SSL checking:

    git config --global http.sslVerify false
    Or the CA certificate can be added to the client machine, this means adding the ./keys/ca.crt file to the set of CA certificates the client system accepts. Instructions for doing this can be found here: http://askubuntu.com/questions/73287/how-do-i-install-a-root-certificate

    7.7 Tips & Warnings

    1. When using Gitolite with http, any repository wish to allow access over apache must have R=daemon added to its permissions you can then add the Apache users individual permissions to the repo.
    2. Following installation of Gitolite may need to run command below to set same permissions on new Gitolite folders as the rest of home directory.
      # restorecon -R -v /home
    3. If creating a repository via Gitolite this will be created on all nodes as a bare repo, This repository can then be added to GitMS and replicated either in same group as admin repository or in a separate group with its own node roles and schedule.
    4. Gitolite's documentation currently states no SeLinux rules to allow gitolite over httpd, It's answer is to install in a directory already allowed under selinux from gitolite documentation: If your server is running SELinux, and you install gitolite to /var/gitolite or another location unsupported by default SELinux policies, then SELinux will prevent sshd from reading .ssh/authorized_keys. Consider installing gitolite to /var/lib/gitolite, which is a supported location by default SELinux policies.