How to Monitor GitBucket with Vigilmon (API Health, Git SSH, and JVM Alerts)

GitBucket is a self-hosted GitHub clone built on the JVM using Scala. It gives teams a familiar Git hosting experience — pull requests, wikis, issue tracking — without sending code to a third-party service. But a JVM application running on your own hardware has failure modes that need active monitoring: heap exhaustion, port binding failures, and slow API responses that precede a full crash.

This tutorial shows you how to monitor GitBucket end-to-end using Vigilmon — covering the web UI, the REST API, Git SSH, and SSL certificates.

Why GitBucket needs dedicated monitoring

GitBucket runs as a Java process (via the bundled Jetty server), which introduces JVM-specific failure modes alongside standard web service issues:

JVM heap exhaustion — as repositories grow and users clone large repos, the JVM heap fills and response times spike before the process crashes with OutOfMemoryError
Git SSH daemon failures — GitBucket bundles an SSH server for Git operations on port 29418. This can fail independently of the web UI
War file deployment issues — if you run GitBucket as a .war file in Tomcat, a bad deployment can leave the HTTP server running but GitBucket itself broken
Plugin compatibility crashes — GitBucket plugins can cause startup failures that the HTTP server masks with generic 500 errors

External monitoring from Vigilmon detects all of these from the outside, before developers start complaining that git push is failing.

What you'll need

A running GitBucket instance (default port 8080 or behind a reverse proxy on 443)
A free Vigilmon account (sign up takes under a minute)

Step 1: Confirm the API health endpoint

GitBucket exposes a GitHub-compatible REST API at /api/v3. The /api/v3/user endpoint returns the authenticated user, but for anonymous health checks the base path /api/v3 returns API metadata:

curl -i https://gitbucket.your-domain.com/api/v3

Expected response:

{
  "current_user_url": "https://gitbucket.your-domain.com/api/v3/user",
  "authorizations_url": "https://gitbucket.your-domain.com/api/v3/authorizations"
}

Any response with HTTP 200 here confirms that GitBucket's web layer and API routing are functional. If you have authentication enabled, you can pass a personal access token:

curl -H "Authorization: token YOUR_PAT" https://gitbucket.your-domain.com/api/v3/user

For monitoring purposes, the unauthenticated /api/v3 base path is sufficient and doesn't require storing credentials in Vigilmon.

Step 2: Set up HTTP monitoring for the web UI

Log in to vigilmon.online and go to Monitors → New Monitor
Choose HTTP / HTTPS
URL: https://gitbucket.your-domain.com/
Check interval: 1 minute
Expected status code: 200
(Optional) Response body contains: GitBucket
Save the monitor

This catches web server failures, Jetty crashes, and cases where GitBucket's war file fails to initialize.

Step 3: Set up the API health monitor

Add a separate monitor specifically for the REST API path:

Monitors → New Monitor → HTTP / HTTPS
URL: https://gitbucket.your-domain.com/api/v3
Check interval: 2 minutes
Expected status code: 200
Response body contains: current_user_url
Save the monitor

This monitor validates the API routing layer independently of the web UI. A broken plugin or bad database migration can break the API while the login page still renders.

Step 4: Monitor the Git SSH service

GitBucket's SSH Git server runs on port 29418 by default (or a custom port you configured). SSH port monitoring with Vigilmon uses TCP checks:

Monitors → New Monitor → TCP Port
Host: gitbucket.your-domain.com
Port: 29418 (or your configured SSH port)
Check interval: 2 minutes
Save the monitor

When this monitor fires, it means git clone git@gitbucket.your-domain.com:org/repo.git will fail for all developers — a high-priority alert.

Step 5: Set up JVM heap health monitoring via response time

JVM heap pressure shows up as response time degradation before it causes a crash. As the garbage collector works harder, response times climb from 50ms to 500ms to several seconds — and then the process dies.

Configure a response time threshold on your web UI monitor:

Open the web UI HTTP monitor
Settings → Response Time Alert
Set threshold: 3000ms (3 seconds)
Save

When GitBucket's response time exceeds 3 seconds, Vigilmon alerts you. This is your signal to check JVM heap usage (jstat -gcutil, JMX metrics, or your APM tool) before the process crashes.

You can also tune the JVM heap in your startup script to prevent this:

java -Xms512m -Xmx2g -jar gitbucket.war

Adjust -Xmx based on your server's available RAM and repository sizes.

Step 6: SSL certificate monitoring

Developers trust your internal Git host implicitly. A certificate expiry that breaks HTTPS will block all git push and git pull operations that use the HTTPS remote URL.

Monitors → New Monitor → SSL Certificate
Domain: gitbucket.your-domain.com
Alert at 30 days before expiry (critical at 7 days)
Save

Step 7: Configure alert channels

Alert Channels → Add Channel
Set up Slack or Email — or both
Assign all monitors to the alert channel

For engineering teams, a dedicated #gitbucket-alerts Slack channel is effective — it keeps Git infrastructure alerts separate from application alerts and makes on-call rotation easier.

Monitor summary

| Monitor | Type | Interval | What it catches | |---------|------|----------|-----------------| | Web UI / | HTTP | 1 min | Jetty crashes, war file failures | | API /api/v3 | HTTP | 2 min | Plugin failures, routing errors | | SSH port 29418 | TCP | 2 min | Git SSH service failures | | SSL certificate | SSL | Daily | Certificate expiry | | Response time > 3s | Threshold | — | JVM heap pressure |

What's next

Heartbeat monitoring — if you run GitBucket backup scripts or mirror scripts via cron, add heartbeat monitors to catch silent job failures
Status page — publish a status page for your team so developers can self-check during an outage instead of filing support tickets

Get started free at vigilmon.online — no credit card required, monitors start running in under a minute.