Monitoring Trunk.io with Vigilmon

Trunk is a developer experience platform that unifies linting, formatting, merge queue management, and CI analytics into a single toolchain. The self-hosted Trunk deployment includes Trunk Check (code quality and linting runner), Trunk Merge (merge queue for CI-gated merges), and Trunk CI Analytics (CI pipeline observability). When Trunk Merge is your gate for getting code into main, its health is your team's shipping velocity.

When Trunk is down or the merge queue is stuck, PRs can't merge. Engineers wait. Releases slip. And unlike an obvious page crash, a stuck merge queue can sit unnoticed while everyone assumes CI is just "taking a while." Vigilmon gives you the monitoring layer that catches Trunk outages and queue anomalies before your team hits a wall.

What You'll Set Up

• Trunk API server uptime monitor (port 3000)
• Dashboard availability check
• Merge queue health heartbeat
• CI signal ingestion probe
• SSL certificate expiry alert
• Alert channels with merge-queue-aware thresholds

Prerequisites

• Trunk self-hosted deployment with the API server running (default port 3000)
• Trunk Merge configured for at least one repository
• A free Vigilmon account

Step 1: Monitor Trunk API Server Availability (Port 3000)

The Trunk API server is the coordination hub for every Trunk service — merge queue processing, linting job dispatch, CI status tracking, and the web dashboard. When this service is down, all merges requiring Trunk approval are blocked, and the queue stops processing entirely.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Trunk API URL: https://trunk.yourdomain.com/api/health (or / if no health endpoint is exposed).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Add a TCP monitor for a lower-level signal:

1. Click Add Monitor → TCP Port.
2. Enter your Trunk server hostname and port 3000.
3. Set Check interval to 1 minute.
4. Click Save.

Step 2: Monitor the Trunk Dashboard

The Trunk web UI at port 3000 is how engineers view queue status, CI analytics, and linting results. If the dashboard is unavailable while the API backend is still up, engineers lose visibility into queue state.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://trunk.yourdomain.com/ (the dashboard root).
3. Set Check interval to 2 minutes.
4. Set Expected HTTP status to 200.
5. Enable Keyword check and enter a string unique to the Trunk dashboard HTML (e.g., Trunk or the page title).
6. Click Save.

Step 3: Monitor Merge Queue Health with a Heartbeat

Trunk Merge serializes concurrent PRs into a queue, runs CI for each, and merges only when CI passes. A queue can get stuck when CI signals stop arriving, a PR is in a permanently failing state and blocks the train, or the Trunk service loses its GitHub App connection.

Use Vigilmon's cron heartbeat to confirm the merge queue is actively processing:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 30 minutes.
3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Create a health check script that queries the Trunk API for queue activity and pings the heartbeat if the queue is healthy:

#!/bin/bash
# /etc/cron.d/trunk-queue-heartbeat — runs every 15 minutes
TRUNK_API="https://trunk.yourdomain.com"
HEARTBEAT="https://vigilmon.online/heartbeat/abc123"

# Check that the API is up and the queue endpoint responds
STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$TRUNK_API/api/queue/status")

if [ "$STATUS" = "200" ]; then
  curl -s "$HEARTBEAT"
fi

If the Trunk API stops responding, the script never pings, and Vigilmon alerts after 30 minutes.

Step 4: Monitor GitHub API Connectivity

Trunk Merge posts merge status checks, required check results, and PR comments through the GitHub API. GitHub API rate limit exhaustion or a stale GitHub App token causes Trunk to make merge decisions based on stale data — or fail to post merge status at all.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://api.github.com/zen.
3. Set Check interval to 5 minutes.
4. Set Expected HTTP status to 200.
5. Click Save.

For rate limit monitoring, add a secondary heartbeat pinged by a cron script that checks Trunk's GitHub API rate limit headroom:

#!/bin/bash
# Check GitHub API rate limit headroom for Trunk's GitHub App token
REMAINING=$(curl -s -H "Authorization: token $TRUNK_GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq '.rate.remaining')

# Alert if fewer than 500 requests remain in the current window
if [ "$REMAINING" -gt 500 ]; then
  curl -s https://vigilmon.online/heartbeat/rate-limit-ok-abc123
fi

Step 5: Monitor CI Signal Ingestion

Trunk Merge waits for CI status checks from GitHub Actions, CircleCI, or Jenkins before merging. If CI signal delivery stalls — GitHub webhooks are delayed, or a CI provider's status API is down — Trunk sits waiting on a "pending" check that never resolves, blocking the entire queue.

Add a keyword monitor that checks Trunk's CI signal freshness endpoint (if your Trunk deployment exposes one):

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://trunk.yourdomain.com/api/ci/last-signal (adjust to your Trunk API path).
3. Set Check interval to 5 minutes.
4. Enable Keyword check — look for a timestamp field or a status value indicating recent activity.
5. Click Save.

Alternatively, use a cron heartbeat approach where your CI pipeline pings Vigilmon after each completed run:

# .github/workflows/ci.yml — add to the final step
- name: Ping Vigilmon CI signal heartbeat
  if: always()
  run: curl -s https://vigilmon.online/heartbeat/ci-signal-abc123

If CI stops running entirely (e.g., GitHub Actions outage), this heartbeat goes silent and Vigilmon alerts.

Step 6: SSL Certificate Expiry Alert

1. Open the HTTP monitor for your Trunk API (Step 1).
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

An expired certificate on the Trunk API causes the GitHub App webhook delivery to fail with a TLS error, effectively taking down the entire merge queue.

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or PagerDuty.
2. For the Trunk API monitor and TCP port monitor: set Consecutive failures before alert to 1. Trunk API downtime is a blocking incident — your entire merge queue is frozen.
3. For the GitHub API monitor: set Consecutive failures before alert to 3. Transient GitHub API blips don't mean Trunk is broken.
4. For the merge queue heartbeat: leave the default of 1 missed heartbeat (30 minutes of queue inactivity warrants a look).

Create a Maintenance window before Trunk upgrades:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "trunk-api-monitor-id", "duration_minutes": 15}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | Trunk API HTTP | https://trunk.yourdomain.com/api/health | Service crash, API unavailability | | TCP port | :3000 | Process down, port not listening | | Dashboard | https://trunk.yourdomain.com/ | UI unavailability | | SSL certificate | Trunk domain | Certificate expiry, TLS failure | | Merge queue heartbeat | Heartbeat URL | Queue stuck, Trunk-GitHub connection lost | | GitHub API | api.github.com/zen | GitHub API reachability | | CI signal heartbeat | Heartbeat URL | CI pipeline stopped, stale CI signals |

When Trunk Merge is your team's merge gate, its health is your team's shipping health. A 5-minute Trunk outage during a busy afternoon can result in hours of queued PRs. With Vigilmon monitoring the API, queue health, and CI signal ingestion, you get the instant visibility to know the difference between "CI is slow" and "Trunk is down."