tutorial

Monitoring Gitea with Vigilmon: Web UI, Git Clone Health, SSH Service, API & Disk Usage Alerts

How to monitor Gitea (self-hosted GitHub alternative) with Vigilmon — web UI availability, git HTTP clone endpoint health, SSH service check, API health (/api/v1/version), repository list response time, and disk usage alerting for large repos.

Gitea is the lightweight, self-hosted Git service that teams use to store source code, review pull requests, run CI/CD webhooks, and track issues — all without depending on GitHub or GitLab. When Gitea goes down, developers can't push code, CI pipelines stop triggering, and the issue tracker goes dark. Vigilmon gives you external visibility into every layer of a Gitea installation: the web UI, the API, the git HTTP transport, SSH connectivity, and disk capacity before large repositories fill your storage.

What You'll Build

  • An HTTP monitor on Gitea's API health endpoint (/api/v1/version)
  • A web UI availability check that catches process crashes and routing failures
  • A git HTTP clone endpoint check for transport-layer health
  • SSH port monitoring for key-based git operations
  • Response time alerting for the repository list page
  • SSL certificate monitoring for your Gitea domain
  • A disk usage heartbeat to catch storage pressure before repos stop accepting pushes

Prerequisites

  • Gitea running (typically on port 3000 or behind a reverse proxy)
  • A domain or IP:port accessible externally over HTTPS
  • A free account at vigilmon.online

Step 1: Check Gitea's API Health Endpoint

Gitea exposes /api/v1/version — an unauthenticated endpoint that returns the running server version. It's the fastest way to confirm Gitea is alive and its API layer is responding:

curl https://git.yourdomain.com/api/v1/version
# {"version":"1.21.0"}

A non-200 response or connection refused means Gitea has crashed, the database connection is broken, or a reverse proxy is misconfigured.

Step 2: Create the API Health Monitor in Vigilmon

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://git.yourdomain.com/api/v1/version
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: version (matches the JSON response body).
  7. Label: Gitea API Health
  8. Click Save.

This monitor catches:

  • Gitea process crashes or OOM kills
  • Database connection failures (Gitea returns 500 when it can't reach its DB)
  • Reverse proxy routing failures to port 3000
  • DNS resolution errors on your Gitea domain

Step 3: Monitor the Web UI Availability

The API endpoint doesn't exercise the full frontend rendering stack. Add a separate monitor for the Gitea homepage to confirm the web UI, session store, and template rendering are all working:

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

If the API check passes but the web UI check fails, the problem is in Gitea's frontend rendering layer rather than a total process crash.

Step 4: Verify the Git HTTP Clone Endpoint

Git operations over HTTPS use Gitea's smart HTTP transport. When this breaks, git clone, git fetch, and git push all fail for developers — even while the web UI looks healthy. Probe the git-upload-pack info endpoint to confirm transport health:

curl -I "https://git.yourdomain.com/info/refs?service=git-upload-pack"
# HTTP/2 401 (authentication required — confirms transport is alive)
# or HTTP/2 200 for public-repo servers

A 401 or 200 both confirm the git HTTP transport is functional. A 502 or connection refused means it's broken.

  1. Add Monitor → HTTP.
  2. URL: https://git.yourdomain.com/info/refs?service=git-upload-pack
  3. Expected status: 401 (or 200 if public repos are enabled).
  4. Check interval: 300 seconds.
  5. Label: Gitea Git HTTP Transport

Step 5: Monitor the SSH Service Port

Most developers authenticate with SSH keys and use git@git.yourdomain.com:... clone URLs. Gitea's built-in SSH server can crash independently from the main web process. Add a TCP port check:

  1. Add Monitor → Port/TCP.
  2. Host: git.yourdomain.com
  3. Port: 22 (or your configured Gitea SSH port, e.g. 2222).
  4. Check interval: 120 seconds.
  5. Response timeout: 10 seconds.

An SSH port monitor catches cases where the built-in SSH server fails independently from Gitea's HTTP stack — a scenario the web UI and API monitors won't catch.

Step 6: Track Repository List Response Time

The repository explore page (/explore/repos) queries the database for all public repositories and is a good proxy for Gitea's overall database performance. Slow response times here often precede broader failures.

In the Gitea Web UI monitor:

  1. Open monitor settings → Response time alerts.
  2. Warn at: 3 seconds.
  3. Critical at: 8 seconds.

Or add a dedicated monitor for the explore page:

  1. Add Monitor → HTTP.
  2. URL: https://git.yourdomain.com/explore/repos
  3. Response time warn: 3000 ms.
  4. Label: Gitea Repo List Latency

Increasing response times on this page typically indicate database pressure from large repository counts or growing commit history.

Step 7: Monitor Your SSL Certificate

A lapsed SSL certificate blocks every developer from cloning, pushing, or accessing the web UI — and the error message (SSL certificate problem: certificate has expired) is not always immediately obvious:

  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.

Let's Encrypt certificates expire every 90 days. The 30-day threshold catches renewal failures with time to fix them before developers are blocked.

Step 8: Disk Usage Heartbeat for Large Repositories

Gitea stores all git objects on disk. When disk usage hits 100%, new pushes fail with cryptic errors and Gitea itself may crash. Set up a server-side heartbeat that only fires when disk is healthy:

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

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

In Vigilmon:

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

When disk usage exceeds 85%, the heartbeat stops firing and Vigilmon alerts you — before repositories stop accepting pushes.

Common Gitea Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Gitea process OOM-killed | API health check fails within 60 s | | Database connection failure | API returns 500; both monitors alert | | Reverse proxy drops port 3000 routing | Web UI check fails | | SSH built-in server crash (web still running) | SSH TCP monitor fires | | Let's Encrypt certificate expires unnoticed | SSL monitor alerts at 30 days | | Git HTTP transport broken after upgrade | HTTP transport check returns 502 | | Disk full — pushes refused | Disk heartbeat stops; alert fires | | Slow queries from large repo history | Response time alert fires before outage | | DNS misconfiguration after migration | All monitors fire simultaneously |

Gitea's simplicity is a feature — but it also means there's no managed infrastructure watching over it. A Vigilmon setup covering the API, web UI, git transport, SSH, SSL, and disk health gives you external visibility into every failure mode before your team hits a wall.

Start monitoring Gitea 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