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. Like Gitea (which it closely resembles), Forgejo is the kind of infrastructure that developers rely on constantly but rarely think about until it goes down: a broken SSH port means git push fails silently, a web UI outage blocks pull request reviews, and an expired SSL certificate breaks every CI runner and developer machine at once. Vigilmon gives you external visibility into Forgejo's health API, SSH port, web UI, REST API, and SSL certificate.
What You'll Build
- A monitor on Forgejo's
/-/healthAPI endpoint - A TCP monitor for SSH port availability
- An HTTP monitor for the Forgejo web UI
- A monitor for the Forgejo REST API
- SSL certificate monitoring for your Forgejo domain
Prerequisites
- A running Forgejo instance with a public or network-reachable domain
- HTTPS configured for the web UI (e.g.,
https://git.example.com) - SSH access enabled (default port 22 or a custom port)
- A free account at vigilmon.online
Forgejo vs Gitea: Monitoring Differences
Forgejo is a soft fork of Gitea that maintains API and configuration compatibility. For monitoring purposes, they are nearly identical:
| Feature | Forgejo | Gitea |
|---|---|---|
| Health endpoint | /-/health (returns OK) | /-/health (returns OK) |
| API version endpoint | /api/v1/version | /api/v1/version |
| SSH port | 22 (default) | 22 (default) |
| Web UI keyword | Forgejo | Gitea |
| ACME/Let's Encrypt | Built-in (same as Gitea) | Built-in |
The only monitoring difference is the web UI keyword: Forgejo pages use Forgejo in the page title, not Gitea. All endpoint paths, status codes, and response formats are identical.
Step 1: Verify Forgejo's Health API
Forgejo exposes a built-in health endpoint at /-/health:
curl https://git.example.com/-/health
A healthy Forgejo returns HTTP 200 with a plain text body:
OK
This endpoint is unauthenticated and lightweight — it confirms Forgejo's web server is running and its internal health checks pass, including database connectivity.
Step 2: Create a Vigilmon HTTP Monitor for the Health API
- Log in to Vigilmon → Add Monitor → HTTP.
- URL:
https://git.example.com/-/health. - Check interval: 60 seconds.
- Response timeout: 10 seconds.
- Expected status:
200. - Keyword:
OK. - Click Save.
This monitor catches:
- Forgejo process crashes or unexpected restarts
- Database connectivity failures (Forgejo's health check includes DB connectivity)
- Deployment failures after upgrades
- Configuration errors that prevent Forgejo from starting
Step 3: Create a TCP Monitor for SSH Port
SSH is how developers and CI/CD runners push and pull code. HTTP monitors can't verify SSH availability — you need a TCP-level check for the port:
- Add Monitor → TCP.
- Host:
git.example.com. - Port:
22(or your custom SSH port, e.g.,2222). - Check interval: 60 seconds.
- Response timeout: 10 seconds.
- Label:
Forgejo SSH port. - Click Save.
This monitor fires when:
- The SSH daemon (sshd or Forgejo's built-in SSH server) stops responding
- A firewall rule blocks port 22
- The host is unreachable at the network level
When the SSH monitor fires but the HTTP health monitor is green, you have a network or firewall issue specific to the SSH port — the Forgejo process is running but SSH is blocked. This distinction is crucial for fast incident diagnosis: developers using HTTPS for Git operations are unaffected, while SSH users are blocked.
Step 4: Monitor the Forgejo Web UI
The /-/health endpoint confirms Forgejo is alive, but the web UI involves additional layers: reverse proxies, static asset serving, and template rendering. Add a monitor for the main Forgejo interface:
- Add Monitor → HTTP.
- URL:
https://git.example.com. - Check interval: 60 seconds.
- Expected status:
200. - Keyword:
Forgejo. - Label:
Forgejo Web UI. - Click Save.
Migrating from Gitea? If you renamed your instance and changed the page title, use your custom instance name as the keyword. The default
Forgejokeyword appears in the HTML<title>of every page on a standard installation.
This monitor catches reverse proxy failures, TLS termination issues, and template rendering problems that wouldn't affect the health API but would block developers from accessing the web interface.
Step 5: Monitor the Forgejo REST API
Forgejo's REST API powers integrations, webhooks, CI/CD triggers, and third-party tooling. Monitor the API version endpoint as a lightweight, unauthenticated check:
curl https://git.example.com/api/v1/version
A healthy API returns:
{"version": "1.21.0-0"}
The version format includes the Forgejo-specific suffix (e.g., -0) that distinguishes it from Gitea's version strings.
- Add Monitor → HTTP.
- URL:
https://git.example.com/api/v1/version. - Check interval: 5 minutes.
- Expected status:
200. - Keyword:
version. - Label:
Forgejo API. - Click Save.
When the API monitor fires but the web UI monitor is green, you have an API routing issue — possibly a reverse proxy misconfiguration or an API-layer error introduced by an upgrade.
Step 6: Monitor SSL Certificates
A Forgejo SSL certificate expiry breaks multiple things simultaneously:
- Developers get TLS errors when visiting the web UI
git clone https://...fails on all developer machines and CI runners- Webhook deliveries to HTTPS endpoints fail
- Package registry integrations (if enabled) break
- Add Monitor → SSL Certificate.
- Domain:
git.example.com. - Alert when expiry is within: 30 days.
- Alert again: 14 days, 7 days, 3 days, 1 day.
- Click Save.
If Forgejo uses Let's Encrypt via its built-in ACME support ([server] ENABLE_ACME = true in app.ini), a 30-day warning means automatic renewal has failed. Check the Forgejo logs for ACME errors before the certificate expires.
Step 7: Configure Alerting
In Vigilmon under Settings → Notifications, configure your alert channels:
| Monitor | Trigger | Action |
|---|---|---|
| /-/health | Non-200 or OK missing | Check systemctl status forgejo; inspect Forgejo logs |
| SSH TCP port | Connection refused or timeout | Check firewall rules; verify SSH daemon is running |
| Web UI | Non-200 or Forgejo missing | Check reverse proxy (nginx/Caddy); review TLS config |
| API /api/v1/version | Non-200 or version missing | API routing issue; check Forgejo config and reverse proxy |
| SSL certificate | < 30 days to expiry | Renew certificate; check ACME automation |
Alert after: 2 consecutive failures for HTTP monitors (brief network blips can trigger false positives). 1 failure for TCP monitors — TCP connection failures are rarely transient.
Common Forgejo Failure Modes and What Vigilmon Catches
| Scenario | Vigilmon monitor |
|---|---|
| Forgejo process crash | /-/health unreachable; alert within 60 s |
| Database goes down | /-/health returns non-200; Forgejo can't serve pages |
| SSH port blocked by firewall | TCP monitor fires; HTTP monitors stay green |
| Built-in SSH server crashes | TCP monitor fires; /-/health stays green |
| Reverse proxy misconfiguration | Web UI monitor fires; /-/health may stay green |
| SSL certificate expires | SSL monitor alerts at 30-day threshold; all HTTPS breaks |
| Disk full → can't accept pushes | /-/health may stay green; SSH and HTTPS pushes fail |
| DNS misconfiguration | All HTTP and SSL monitors fire simultaneously |
| Upgrade breaks API compatibility | API monitor fires; web UI may still work |
| Git repositories corrupted | Health endpoint stays green; specific repo operations fail |
Self-hosted Git is infrastructure your team relies on every day, but it only gets attention when something breaks. Forgejo's /-/health endpoint, SSH port, web UI, and REST API each cover different failure modes — a firewall change, a certificate expiry, and a process crash all look different in monitoring. Vigilmon watches all four 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.