tutorial

Monitoring Gitolite with Vigilmon: SSH Access, Admin Repo Health, Repository Push Tests & Companion Web UI Checks

How to monitor Gitolite (the SSH-based Git hosting access control layer) with Vigilmon — SSH port availability, admin repo connectivity, repository push health, companion web frontend (cgit/gitweb), and disk usage heartbeats.

Gitolite is the industry-standard Git hosting access control layer used to manage SSH-based access to multiple Git repositories on a single server. Unlike full Git forges, Gitolite has no web UI of its own — it's a sophisticated authorized_keys manager combined with a per-repository permission system, all operating entirely over SSH. Organizations running Gitolite often pair it with Cgit or Gitweb for read-only browser access. When Gitolite breaks, developers can't push or pull code at all — and the failure is often silent, manifesting only as a cryptic Permission denied (publickey) SSH error. Vigilmon gives you external visibility into Gitolite's SSH access layer, the companion web frontend, and disk health on the repository storage volume.

What You'll Build

  • An SSH port monitor confirming the sshd that Gitolite hooks into is reachable
  • A cron heartbeat verifying Gitolite's SSH access works end-to-end
  • A companion web frontend monitor (cgit or gitweb) for read access
  • A disk usage heartbeat for the repository storage volume
  • SSL certificate monitoring if your companion web frontend uses HTTPS

Prerequisites

  • Gitolite installed and configured (typically as the git user on a Linux server)
  • SSH access to the server from a machine with a configured Gitolite key
  • A companion web frontend (cgit or gitweb) if you want HTTP monitoring
  • A free account at vigilmon.online

Step 1: Understand Gitolite's Architecture

Gitolite operates entirely through SSH. When a developer runs git push git@git.yourdomain.com:username/repo.git, the SSH server authenticates them using their public key in /home/git/.ssh/authorized_keys, then Gitolite's gitolite-shell script intercepts the connection, checks permissions in the gitolite-admin repository's conf/gitolite.conf file, and either allows or denies the git operation.

The failure modes are:

  1. SSH daemon stopped (sshd down) — no one can connect
  2. Gitolite's authorized_keys corrupted or overwritten — authentication fails
  3. The gitolite-shell binary missing or non-executable — SSH connects but git operations fail
  4. The repository storage disk full — pushes fail with cryptic errors
  5. Permission misconfiguration in gitolite.conf — specific users/repos blocked

Step 2: Monitor the SSH Port

The most fundamental Gitolite health check is confirming the SSH port is open and accepting TCP connections. This single check catches the most common and most severe failure mode:

  1. Log in to Vigilmon → Add Monitor → Port/TCP.
  2. Host: git.yourdomain.com
  3. Port: 22 (or your configured SSH port).
  4. Check interval: 60 seconds.
  5. Response timeout: 10 seconds.
  6. Label: Gitolite SSH Port
  7. Click Save.

A TCP port failure means developers can't push or pull from any Gitolite-managed repository. This monitor catches sshd process crashes, firewall rule changes, and server reboots that don't bring sshd back up automatically.

Step 3: Verify Gitolite SSH Access End-to-End with a Heartbeat

A TCP port being open doesn't mean Gitolite is working — the gitolite-shell could be broken, the authorized_keys file could be misconfigured, or the git user's home directory permissions could have changed. Set up a cron heartbeat that actually authenticates to Gitolite and runs a harmless info command:

#!/bin/bash
# /etc/cron.d/gitolite-heartbeat — runs every 5 minutes
# Run as a user with a configured Gitolite SSH key

RESULT=$(ssh -o BatchMode=yes -o ConnectTimeout=10 git@git.yourdomain.com info 2>&1)
if echo "$RESULT" | grep -q "hello"; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-HEARTBEAT-ID
fi

The ssh git@git.yourdomain.com info command runs Gitolite's info subcommand, which returns a list of repositories the authenticated user can access. A successful response includes hello <username>. This command is completely safe — it's read-only and built into Gitolite.

In Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Expected interval: 5 minutes.
  3. Grace period: 15 minutes.
  4. Label: Gitolite SSH End-to-End

This heartbeat catches everything the TCP port check misses: broken authorized_keys, missing gitolite-shell binary, and git user home directory permission problems.

Step 4: Test Repository Push Reachability

For even deeper verification, test that a specific repository is reachable over git-upload-pack (the protocol used for git fetch and git clone). This verifies the full Gitolite permission chain for a specific repo:

#!/bin/bash
# /etc/cron.d/gitolite-repo-heartbeat — runs every 10 minutes
# Run as a user with read access to the gitolite-admin repo

RESULT=$(git ls-remote git@git.yourdomain.com:gitolite-admin 2>&1)
if [ $? -eq 0 ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-REPO-HEARTBEAT-ID
fi

In Vigilmon, create a Heartbeat monitor with a 30-minute grace period labeled Gitolite Admin Repo Access.

The gitolite-admin repository is the one repository every Gitolite installation always has. If this heartbeat fails while the SSH end-to-end check passes, the problem is specific to this repository's permissions rather than the Gitolite installation as a whole.

Step 5: Monitor Your Companion Web Frontend

Most Gitolite installations pair with a read-only web frontend — typically Cgit or Gitweb — served by Apache or nginx. Add HTTP monitoring for the web UI:

For Cgit:

  1. Add Monitor → HTTP.
  2. URL: https://git.yourdomain.com/
  3. Expected status: 200.
  4. Keyword: cgit (present in the page footer).
  5. Check interval: 120 seconds.
  6. Label: Gitolite Web Frontend (cgit)

For Gitweb:

  1. Add Monitor → HTTP.
  2. URL: https://git.yourdomain.com/gitweb/
  3. Expected status: 200.
  4. Keyword: projects (present in the project list page).
  5. Check interval: 120 seconds.
  6. Label: Gitolite Web Frontend (gitweb)

The web frontend and the SSH access layer can fail independently. A developer browsing cgit while pushes are silently failing is a real scenario — both monitors are needed.

Step 6: Monitor Your SSL Certificate

If your companion web frontend uses HTTPS (and it should), monitor the SSL certificate:

  1. Add Monitor → SSL Certificate.
  2. Domain: git.yourdomain.com
  3. Alert when expiry is within: 30 days.
  4. Alert again: 14 days, 7 days, 3 days.

Note: Gitolite's SSH authentication itself doesn't use SSL certificates — the SSH layer uses its own host key mechanism. This monitor protects only the HTTPS web frontend.

Step 7: Disk Usage Heartbeat for Repository Storage

Gitolite stores all repositories as bare Git directories, typically under /home/git/repositories/. When this volume fills up, pushes fail with error: remote unpack failed. fatal: Unpack-objects abnormal exit — confusing messages that don't immediately point to disk space as the cause. Set up a disk health heartbeat:

#!/bin/bash
# /etc/cron.d/gitolite-disk-heartbeat — runs every 5 minutes

DISK_USAGE=$(df /home/git/repositories --output=pcent | tail -1 | tr -d '% ')
if [ "$DISK_USAGE" -lt 85 ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-DISK-HEARTBEAT-ID
fi

In Vigilmon:

  1. Add Monitor → Heartbeat.
  2. Expected interval: 5 minutes.
  3. Grace period: 15 minutes.
  4. Label: Gitolite Repository Disk Health

When disk usage exceeds 85%, the heartbeat stops and Vigilmon alerts you before developers start seeing cryptic push failures.

Step 8: Alert on Gitolite Admin Repository Changes

Gitolite's access control is entirely managed through the gitolite-admin repository. Unexpected changes to this repository — misconfigured permissions, accidental key removals — can silently lock developers out. Add a cron check that monitors the admin repo's most recent commit:

#!/bin/bash
# /etc/cron.d/gitolite-admin-check — runs every 15 minutes
# Runs on the Gitolite server itself as the git user

COMMIT=$(git -C /home/git/repositories/gitolite-admin.git log -1 --format="%H %ae %s" 2>&1)
echo "$(date): $COMMIT" >> /var/log/gitolite-admin-changes.log

# Always send heartbeat — the log is the audit trail
curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-ADMIN-AUDIT-HEARTBEAT-ID

Use this log alongside Vigilmon's access timeline to correlate admin repo changes with developer access failures.

Common Gitolite Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | sshd stopped or firewall rule changed | SSH TCP port monitor fires within 60 s | | authorized_keys overwritten or corrupted | SSH end-to-end heartbeat stops | | gitolite-shell missing after system update | SSH end-to-end heartbeat stops | | git user home directory permissions changed | SSH end-to-end heartbeat stops | | Specific repository permissions misconfigured | Admin repo heartbeat fails | | Web frontend (cgit/gitweb) crashes | Web frontend HTTP monitor alerts | | Let's Encrypt certificate expired (web UI) | SSL monitor alerts at 30 days | | Disk full — push failures | Disk heartbeat stops; alert fires | | Server reboot without sshd autostart | SSH port monitor fires within 60 s |

Gitolite's simplicity is a feature — no running daemon, no database, no complex web application. But that same simplicity means there's no built-in health monitoring and failures are often silent. A Vigilmon setup covering the SSH port, end-to-end SSH authentication, repository access, companion web frontend, SSL, and disk health gives you complete external visibility into every layer of a Gitolite deployment.

Start monitoring Gitolite in under 5 minutes — register free at vigilmon.online.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles