Gitolite Deployment and Usage Guide

1. Prerequisites

System Requirements:

Linux/Unix server (Ubuntu 18.04+, Debian 10+, CentOS 7+, or similar)
Git 1.6.6 or newer (git --version)
Perl 5.8.8 or newer (perl -v)
OpenSSH server running on standard port 22 (or custom)
Bash shell

Accounts & Access:

Root or sudo access for initial user creation
Dedicated system user for Gitolite (conventionally named git)
SSH key pair (RSA or Ed25519) for the Gitolite administrator

2. Installation

Step 1: Create the Git User

# On the server
sudo adduser --disabled-password --gecos 'Gitolite User' git
# Or: sudo useradd -m -s /bin/bash git

Step 2: Obtain Gitolite Source

# Switch to git user
su - git

# Clone repository
git clone https://github.com/sitaramc/gitolite.git

# Create local bin directory
mkdir -p ~/bin

# Install gitolite binaries
gitolite/install -to ~/bin

Step 3: Configure PATH Add to ~/.bashrc:

export PATH=$PATH:$HOME/bin

Then reload: source ~/.bashrc

Step 4: Initialize Gitolite From your admin workstation, copy your public key to the server:

scp ~/.ssh/id_rsa.pub git@server:/tmp/admin.pub
# Or for Ed25519: scp ~/.ssh/id_ed25519.pub git@server:/tmp/admin.pub

On the server, setup Gitolite:

su - git
gitolite setup -pk /tmp/admin.pub

3. Configuration

Server-Side Configuration (~/.gitolite.rc) This Perl file controls Gitolite behavior. Key settings:

# Logging level (normal, debug, etc.)
$LOG_EXTRA = 1;

# Enable specific features
$GL_PERFLOGT = 1;

# Custom hooks path
$LOCAL_CODE = "$ENV{HOME}/.gitolite/local";

Repository Administration All repository and user management is done via the gitolite-admin repository:

# On admin workstation
git clone git@server:gitolite-admin
cd gitolite-admin

Directory structure:

conf/gitolite.conf — Access control rules
keydir/ — User SSH public keys (named username.pub)

Example conf/gitolite.conf:

@admins = admin

repo gitolite-admin
    RW+ = @admins

repo testing
    RW+ = @all

repo project1
    RW+ = admin
    RW = alice bob
    R = @developers

Adding Users:

# Copy user's pub key to keydir/
cp /path/to/user.pub keydir/alice.pub
git add keydir/alice.pub
git commit -m "Add alice"
git push

4. Build & Run

No Compilation Required Gitolite is pure Perl; no build step is necessary.

Verification Test the installation:

# From any client
ssh git@server info

Expected output:

hello admin, this is git@server running gitolite3 v3.x-x on git x.x.x

 R W    gitolite-admin
 R W    testing

Local Development/Testing To test configuration changes locally before pushing:

# On server, as git user
gitolite compile  # Compiles conf without activating
gitolite query-rc GL_ADMIN_BASE  # Query specific config

5. Deployment

Production Deployment Checklist

1. Server Hardening

# Disable password authentication for git user
sudo passwd -l git

# Ensure SSH key-only auth in /etc/ssh/sshd_config:
# PasswordAuthentication no
# PubkeyAuthentication yes
# ChallengeResponseAuthentication no

sudo systemctl restart sshd

2. Backup Strategy Backup these directories:

~git/repositories/ — All git repos
~git/.gitolite/ — Gitolite metadata and logs
~git/.gitolite.rc — Configuration file

Example backup script:

#!/bin/bash
tar czf gitolite-backup-$(date +%Y%m%d).tar.gz \
  /home/git/repositories \
  /home/git/.gitolite \
  /home/git/.gitolite.rc

3. Hosting Platforms Gitolite runs on any Linux VPS:

AWS EC2: Ubuntu/Amazon Linux 2 AMI, security group allowing SSH (22)
DigitalOcean Droplet: Ubuntu 20.04+ LTS
Linode: Debian or Ubuntu instance
On-Premise: Any server with SSH access and Perl

4. Updates

# As git user
cd ~/gitolite
git pull
# If install script changed:
gitolite/install -to ~/bin
# Recompile config
gitolite setup

6. Troubleshooting

SSH Connection Issues

Problem: Permission denied (publickey) when connecting

# Diagnose
ssh -v git@server

# Solutions:
# 1. Verify key is in gitolite-admin/keydir/ and pushed
# 2. Check server: cat ~git/.ssh/authorized_keys | grep gitolite
# 3. Ensure correct permissions: chmod 700 ~git/.ssh; chmod 600 ~git/.ssh/authorized_keys

Repository Access Denied

Problem: R access for repo denied or W access for repo denied

Verify conf/gitolite.conf syntax: gitolite compile (from server)
Check username matches key filename in keydir/ (case-sensitive)
Ensure you pushed admin repo changes: git push from gitolite-admin

Gitolite Commands Not Found

Problem: gitolite: command not found

# As git user
echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc
source ~/.bashrc
# Verify
which gitolite

Hook Execution Failures

Problem: Custom hooks not running

Check ~/.gitolite.rc for $LOCAL_CODE setting
Ensure hooks are executable: chmod +x hookname
Check logs: ~git/.gitolite/logs/

Debugging Enable detailed logging temporarily:

# On server, as git user
export GL_DEBUG=1
gitolite compile
# Or for SSH issues
GL_DEBUG=1 ssh git@server info