Monitoring GitStream with Vigilmon

GitStream (by LinearB) is an open source git workflow automation platform that uses a .cm/gitstream.cm configuration file to define automated code review rules — automatically assigning reviewers based on code ownership, labeling PRs by change type, and triggering AI-powered review suggestions. It runs as a self-hosted webhook service that receives GitHub and GitLab events and executes your automation rules in real time.

When GitStream is healthy, developers barely notice it — reviewers get assigned instantly, PRs get labeled, and merge approvals flow. When it breaks, those workflows stop silently. There's no banner or error page. PRs pile up unreviewed, and teams don't notice until someone wonders why reviewers were never assigned hours later. Vigilmon gives you the proactive observability to catch these failures before they become bottlenecks.

What You'll Set Up

• Webhook service uptime monitor for port 3000
• SSL certificate expiry alert for the webhook endpoint
• GitHub API connectivity probe
• Workflow execution health via cron heartbeat
• Alert channels with tuned thresholds

Prerequisites

• GitStream self-hosted deployment with the webhook service running (default port 3000)
• The webhook endpoint accessible over HTTPS
• A free Vigilmon account

Step 1: Monitor Webhook Service Availability (Port 3000)

GitStream's webhook receiver is the central nervous system of your automation. Every PR event, push, and review from GitHub or GitLab flows through it. When this service is down, all automated workflow actions — reviewer assignment, merge approvals, label application — stop immediately.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your GitStream webhook URL: https://gitstream.yourdomain.com/ (or https://gitstream.yourdomain.com/health if you expose a health endpoint).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If GitStream exposes a dedicated health endpoint, use it. You can also add a TCP monitor as a lower-level check:

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

The TCP monitor catches cases where the process is listening but the HTTP layer is failing, giving you two independent signals.

Step 2: SSL Certificate Expiry Alert

GitStream's webhook endpoint must use HTTPS — GitHub and GitLab validate the SSL certificate before delivering events. If the certificate expires, GitHub stops delivering webhooks and all automation halts silently.

1. Open the HTTP monitor you created in 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.

A 21-day window gives you enough time to renew before GitHub stops delivering events. If you use Let's Encrypt with auto-renewal, this alert catches renewal failures before they reach the critical 0-day expiry that breaks webhook delivery.

Step 3: Monitor GitHub API Connectivity

GitStream reads PR diffs, assigns reviewers, adds labels, and posts comments through the GitHub API. If GitStream's API token is expired, its rate limit headroom is exhausted, or GitHub's API is degraded, workflow actions fail silently — the webhook is received, but the downstream actions never execute.

Add a keyword monitor to verify GitHub API connectivity from your GitStream server:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: https://api.github.com/zen (GitHub's publicly accessible API health endpoint — returns a motivational string with status 200).
3. Set Check interval to 5 minutes.
4. Set Expected HTTP status to 200.
5. Enable Keyword check and enter half measures (any GitHub zen response word works — GitHub returns a random phrase each time, but status 200 confirms reachability).
6. Click Save.

This probes GitHub API reachability. For rate limit monitoring, add a heartbeat that your GitStream deployment pings after each successful API call batch — covered in Step 5.

Step 4: Verify Workflow Execution with a Cron Heartbeat

GitStream's internal workflow executor parses .cm/gitstream.cm rules and evaluates them against each PR event. If there's a syntax error in a rule file, a misconfigured CODEOWNERS integration, or an LLM API key that has expired (for AI review features), rule execution silently fails.

Use Vigilmon's cron heartbeat to verify that GitStream is actually processing events end-to-end:

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

Add a simple GitStream rule that pings the heartbeat on any PR event. In your .cm/gitstream.cm:

manifest:
  version: 1.0

automations:
  heartbeat_ping:
    if:
      - true
    run:
      - action: add-comment@v1
        args:
          comment: ""
      - action: run-script@v1
        args:
          script: |
            curl -s https://vigilmon.online/heartbeat/abc123

Alternatively, configure a server-side cron job that pings the heartbeat after verifying the GitStream process is healthy:

#!/bin/bash
# /etc/cron.hourly/gitstream-heartbeat
if systemctl is-active --quiet gitstream; then
  curl -s https://vigilmon.online/heartbeat/abc123
fi

If GitStream stops processing events or crashes, the heartbeat goes silent and Vigilmon alerts after 60 minutes.

Step 5: Monitor PR Processing Latency

GitStream should process webhook events and complete workflow actions (reviewer assignment, labels, comments) within seconds. Latency above 30 seconds indicates the service is overloaded or the LLM API (for AI review features) is slow.

Add a response time alert to your webhook monitor:

1. Open the HTTP monitor from Step 1.
2. Under Response time, set Alert when response time exceeds 5000 ms.
3. Click Save.

For deeper PR processing latency monitoring, instrument your GitStream deployment to emit a metric after each workflow execution and ping a secondary heartbeat. A 30-second execution window is the threshold beyond which GitHub may time out waiting for a response.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add your preferred channel — Slack, email, PagerDuty, or a webhook.
2. For the webhook service monitor (Step 1): set Consecutive failures before alert to 1. A single failed check on the webhook receiver warrants immediate attention — there's no grace period where automation is "partially working."
3. For the GitHub API monitor (Step 3): set Consecutive failures before alert to 3. Transient GitHub API blips are common; three consecutive failures indicate a real connectivity problem.
4. For the heartbeat monitor (Step 4): leave the default of 1 missed heartbeat before alerting.

Configure a Maintenance window in Vigilmon when deploying GitStream updates:

# Before deploying a GitStream update
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "your-webhook-monitor-id", "duration_minutes": 10}'

# Deploy GitStream update
systemctl restart gitstream

# Maintenance window expires automatically

Summary

| Monitor | Target | What It Catches | |---|---|---| | Webhook HTTP | https://gitstream.yourdomain.com/ | Service crash, deploy failure | | TCP port | :3000 | Process down, port not listening | | SSL certificate | Webhook domain | Certificate expiry, renewal failure | | GitHub API | api.github.com/zen | API reachability, connectivity loss | | Cron heartbeat | Heartbeat URL | Workflow execution failure, process hang | | Response time | Webhook response | Overload, LLM API slowness |

GitStream's value is in the automation it runs invisibly in the background. That invisibility is also its failure mode — when it breaks, nothing announces it. With Vigilmon watching the webhook service, SSL certificate, GitHub API connectivity, and workflow execution heartbeat, you get the visibility that GitStream's silent operation doesn't provide out of the box.