Monitoring Forgejo with Vigilmon: Health API, SSH, Actions Runner, Web UI & Storage Health

Forgejo is the community-driven fork of Gitea — a self-hosted Git forge that gives teams full control over their source code, CI/CD pipelines, and project management without depending on GitHub or GitLab. When Forgejo goes down, developers can't push code, Actions pipelines stop triggering, and SSH clone operations fail silently. Vigilmon gives you external visibility into Forgejo's health API, web UI, git transport, SSH port, Actions runner connectivity, and storage health — covering every failure mode from a crashed process to a full disk.

What You'll Build

• An HTTP monitor on Forgejo's /-/health endpoint
• A web UI availability check for the full frontend stack
• A git HTTP endpoint check for transport-layer health
• A TCP monitor for SSH port availability
• A Forgejo Actions runner connectivity heartbeat
• SSL certificate monitoring for your Forgejo domain
• A storage health heartbeat to catch disk pressure before pushes fail

Prerequisites

• A running Forgejo instance with a public or network-reachable domain
• HTTPS configured via a reverse proxy (e.g., https://git.example.com)
• SSH access enabled (default port 22 or a custom port)
• A free account at vigilmon.online

Step 1: Check Forgejo's Built-In Health Endpoint

Forgejo exposes /-/health — an unauthenticated endpoint that validates the server's internal state including database connectivity:

curl https://git.example.com/-/health
# OK

A healthy Forgejo returns HTTP 200 with a plain-text OK body. A non-200 response means the Forgejo process is down, the database connection has failed, or a startup sequence hasn't completed after a restart.

Step 2: Create the Health Monitor in Vigilmon

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://git.example.com/-/health
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: OK.
7. Label: Forgejo Health
8. Click Save.

This single monitor catches:

• Forgejo process crashes or OOM kills
• Database connection failures (health check includes DB connectivity)
• Deployment failures after version upgrades
• Configuration errors that prevent Forgejo from starting

Step 3: Monitor the Web UI Availability

The /-/health endpoint doesn't exercise the full frontend stack. Add a monitor for the Forgejo homepage to confirm reverse proxy routing, static asset serving, and template rendering are all working:

1. Add Monitor → HTTP.
2. URL: https://git.example.com
3. Expected status: 200.
4. Keyword: Forgejo (in the HTML <title> of every standard page).
5. Check interval: 120 seconds.
6. Label: Forgejo Web UI

If the health check passes but the web UI check fails, the problem is in the reverse proxy or template rendering layer — not the Forgejo process itself.

Step 4: Verify the Git HTTP Endpoint

Teams using HTTPS clone URLs depend on Forgejo's smart HTTP transport. When it breaks, git clone, git fetch, and git push all fail — even while the web UI looks healthy. Probe the transport endpoint directly:

curl -I "https://git.example.com/info/refs?service=git-upload-pack"
# HTTP/2 401 — authentication required (confirms transport is alive)

1. Add Monitor → HTTP.
2. URL: https://git.example.com/info/refs?service=git-upload-pack
3. Expected status: 401 (or 200 for public-repo servers).
4. Check interval: 300 seconds.
5. Label: Forgejo Git HTTP Transport

Step 5: Monitor the SSH Service Port

SSH key-based git operations depend on Forgejo's SSH server, which can crash independently from the HTTP stack. Add a TCP port check:

1. Add Monitor → TCP/Port.
2. Host: git.example.com
3. Port: 22 (or your custom SSH port, e.g. 2222).
4. Check interval: 60 seconds.
5. Response timeout: 10 seconds.
6. Label: Forgejo SSH

When the SSH TCP monitor fires but the health check stays green, you have a network/firewall issue specific to the SSH port — HTTP users are unaffected but SSH users are blocked. This distinction makes triage much faster.

Step 6: Monitor Actions Runner Connectivity

Forgejo Actions (compatible with GitHub Actions workflows) requires runner agents to stay connected to the server. A disconnected runner means CI pipelines queue silently without executing. Use a heartbeat to verify runner health:

On each runner host, set up a cron job that pings Vigilmon only when the runner process is running:

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

if systemctl is-active --quiet forgejo-runner; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-RUNNER-HEARTBEAT-ID
fi

Or for Docker-deployed runners:

*/5 * * * * root docker inspect --format='{{.State.Status}}' forgejo-runner | grep -q running && \
  curl -s https://vigilmon.online/api/heartbeat/YOUR-RUNNER-HEARTBEAT-ID

In Vigilmon:

1. Add Monitor → Heartbeat.
2. Expected interval: 5 minutes.
3. Grace period: 15 minutes.
4. Label: Forgejo Actions Runner

If the runner crashes, disconnects, or the container exits, the heartbeat stops and Vigilmon alerts within the grace period — before your team notices pipelines aren't running.

Step 7: Monitor SSL Certificates

A Forgejo SSL certificate expiry breaks everything simultaneously: web UI access, HTTPS git clone, webhook deliveries, and Actions runner connections all fail with TLS errors:

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

If Forgejo uses its built-in ACME support (ENABLE_ACME = true in app.ini), a 30-day warning means automatic renewal has failed. Check Forgejo logs for ACME errors before the certificate expires and developers start seeing TLS errors on every git operation.

Step 8: Storage Health Heartbeat

Forgejo stores all git objects on disk. When disk usage hits capacity, new pushes fail with cryptic errors and the application may crash. Set up a server-side heartbeat that only pings when disk is healthy:

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

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

In Vigilmon:

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

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

Common Forgejo Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Forgejo process crash | Health check fails within 60 s | | Database connection failure | Health endpoint returns non-200 | | SSH built-in server crash (HTTP still running) | SSH TCP monitor fires | | Reverse proxy misconfiguration | Web UI check fails; health check green | | Git HTTP transport broken after upgrade | HTTP transport check returns 502 | | Actions runner disconnects | Runner heartbeat stops within grace period | | SSL certificate expires | SSL monitor alerts at 30 days | | Disk full — pushes refused | Storage heartbeat stops | | DNS misconfiguration after migration | All monitors fire simultaneously |

Self-hosted Git is infrastructure your team relies on every minute, but it only gets attention when something breaks. Vigilmon watches Forgejo's health API, web UI, git transport, SSH port, Actions runners, and storage health simultaneously — so you know exactly what's broken and can restore access before the next developer hits the error.

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