tutorial

Monitoring Mergify with Vigilmon

Mergify automates PR merges, manages merge queues, and backports to release branches — but when its webhook service is down, all automated merges stop and your merge queue freezes silently. Here's how to monitor Mergify's webhook availability, GitHub API health, and merge queue with Vigilmon.

Mergify is an open source pull request automation and merge queue platform that uses a .mergify.yml configuration file to define automated PR workflows — auto-merging PRs that meet conditions, managing merge queues to serialize CI runs and prevent merge conflicts, backporting merged PRs to release branches, and automatically assigning reviewers. The self-hosted Mergify deployment runs as a GitHub App webhook service built on Python and FastAPI.

Mergify is the final gate between code review and production. When it's healthy, PRs merge automatically the moment CI passes and reviews are approved. When it breaks, the queue freezes, auto-merges stop, and backports don't happen — all without any visible error. Engineers assume CI is slow. Release managers wonder why hotfixes aren't hitting the release branch. Vigilmon gives you the monitoring layer to catch these failures immediately.

What You'll Set Up

  • Webhook service uptime monitor (port 3000)
  • SSL certificate expiry alert for the webhook endpoint
  • GitHub API connectivity and rate limit probe
  • Merge queue health heartbeat
  • CI signal freshness monitor
  • Configuration validation alerting
  • Alert channels with queue-aware thresholds

Prerequisites

  • Mergify self-hosted deployment with the webhook service running (default port 3000)
  • Mergify configured as a GitHub App with webhook delivery enabled
  • A free Vigilmon account

Step 1: Monitor Webhook Service Availability (Port 3000)

Mergify's webhook receiver processes all GitHub PR, push, review, and check run events. Every automated action — evaluating .mergify.yml conditions, queuing PRs, executing merges, triggering backports — begins with a webhook event. When this service is down, GitHub keeps delivering events (with retries), but Mergify never processes them. Once GitHub's retry window expires, those events are gone.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Mergify URL: https://mergify.yourdomain.com/ (or /health if Mergify exposes a health endpoint — FastAPI apps commonly expose /health or /docs).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

Verify your health endpoint:

curl -I https://mergify.yourdomain.com/health
# HTTP/2 200

Add a TCP monitor for a port-level signal:

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

Step 2: SSL Certificate Expiry Alert

GitHub validates Mergify's SSL certificate before delivering webhook events. An expired certificate causes GitHub to stop delivering events immediately — no new PRs enter the queue, no CI results are processed, no merges happen. The failure is silent unless you're watching.

  1. Open the HTTP monitor from 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.

Step 3: Monitor GitHub API Connectivity and Rate Limits

Mergify is unusually API-intensive compared to other GitHub automation tools. For each PR, Mergify reads PR metadata, evaluates CI check statuses, performs the merge, potentially creates a backport branch, and posts status comments — many API calls per PR. In a busy repository, rate limit exhaustion is a real risk.

Add a GitHub API reachability monitor:

  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.

Monitor rate limit headroom with a cron heartbeat:

#!/bin/bash
# /etc/cron.d/mergify-ratelimit — runs every 5 minutes
MERGIFY_GITHUB_TOKEN="$MERGIFY_GITHUB_TOKEN"
HEARTBEAT_OK="https://vigilmon.online/heartbeat/github-rl-ok-abc123"

REMAINING=$(curl -s \
  -H "Authorization: token $MERGIFY_GITHUB_TOKEN" \
  https://api.github.com/rate_limit | jq '.rate.remaining')

# Alert if headroom drops below 500 requests
if [ "${REMAINING:-0}" -gt 500 ]; then
  curl -s "$HEARTBEAT_OK"
fi
  1. In Vigilmon, create a Cron Heartbeat with a 15-minute expected interval.
  2. Use the heartbeat URL in the script above.

When Mergify's GitHub App token approaches rate limit exhaustion, the heartbeat goes silent before API calls start failing.

Step 4: Monitor Merge Queue Health

Mergify's merge queue serializes PRs into a "train" — each PR's CI must pass before the next one can merge. A stuck queue (a PR in a permanently failing state, a CI check that never resolves, a GitHub API timeout during merge) blocks every PR behind it.

Use a cron heartbeat to verify the queue is 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/queue-abc123).

Create a queue health script:

#!/bin/bash
# /etc/cron.d/mergify-queue-health — runs every 10 minutes
MERGIFY_API="https://mergify.yourdomain.com"
HEARTBEAT="https://vigilmon.online/heartbeat/queue-abc123"

# Check that the queue status endpoint responds
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $MERGIFY_API_KEY" \
  "$MERGIFY_API/v1/repos/{owner}/{repo}/queues")

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

Replace {owner}/{repo} with your primary repository. If Mergify loses its GitHub App connection or the queue service crashes, this heartbeat goes silent.

Step 5: Monitor CI Signal Health

Mergify waits for required CI checks to pass before merging a PR. If CI status webhooks stop arriving — because GitHub's check run webhook delivery is delayed, or a CI provider's status API is down — Mergify's queue sits waiting on "pending" checks that never resolve. The entire merge train stalls.

Add a CI signal heartbeat from your CI pipeline:

# .github/workflows/ci.yml — add to the final step of each workflow
- name: Ping Mergify CI signal monitor
  if: always()
  run: |
    curl -s https://vigilmon.online/heartbeat/ci-signal-abc123
  1. In Vigilmon, create a Cron Heartbeat with a 60-minute expected interval.
  2. If CI runs at least once per hour on an active repository, this heartbeat fires regularly. A gap longer than 60 minutes suggests CI has stopped running or webhook delivery has stalled.

Step 6: Monitor .mergify.yml Configuration Health

Mergify parses .mergify.yml from each repository on startup and on each push to the repository. A YAML syntax error or an invalid rule condition causes that repository's entire Mergify configuration to become inactive — auto-merges stop, the queue stops accepting new PRs, and backport rules don't fire. These failures are silent unless you explicitly check config validation status.

Add a keyword monitor that probes Mergify's configuration validation endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://mergify.yourdomain.com/v1/repos/{owner}/{repo}/config (the Mergify API endpoint for configuration status — adjust to your Mergify API version).
  3. Set Check interval to 10 minutes.
  4. Enable Keyword check and check for "valid": true or an equivalent healthy status field.
  5. Set Expected HTTP status to 200.
  6. Click Save.

This catches configuration breakage introduced by a bad push to .mergify.yml before your team notices that auto-merges have quietly stopped working.

Step 7: Monitor Backport Automation

Mergify creates backport PRs when merged PRs match backport rules. A stalled backport worker (job queue backed up, GitHub API permission error on the target branch, persistent rebase conflict) means hotfixes aren't reaching release branches.

Use a cron heartbeat to verify backport jobs are completing:

#!/bin/bash
# /etc/cron.d/mergify-backport — runs every 30 minutes
MERGIFY_API="https://mergify.yourdomain.com"
HEARTBEAT="https://vigilmon.online/heartbeat/backport-abc123"

# Probe the backport job status endpoint
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $MERGIFY_API_KEY" \
  "$MERGIFY_API/v1/repos/{owner}/{repo}/backports/status")

if [ "$STATUS" = "200" ]; then
  curl -s "$HEARTBEAT"
fi
  1. Create a Cron Heartbeat in Vigilmon with a 60-minute expected interval for the backport monitor.

Step 8: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or PagerDuty.
  2. For the webhook service monitor (Steps 1): set Consecutive failures before alert to 1. Mergify downtime is an immediate blocking incident — the merge queue is frozen.
  3. For the GitHub API monitor: set Consecutive failures before alert to 3. Transient GitHub API errors are common; three consecutive failures indicate a real problem.
  4. For the merge queue heartbeat: leave the default of 1 missed heartbeat — 30 minutes without a queue status check warrants investigation.
  5. For the CI signal heartbeat: set Consecutive failures before alert to 1 missed heartbeat — a 60-minute gap in CI runs on an active repo is abnormal.

Add a Maintenance window for Mergify upgrades:

# Suppress alerts during Mergify service restart
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_VIGILMON_API_KEY" \
  -d '{
    "monitor_id": "mergify-webhook-monitor-id",
    "duration_minutes": 10
  }'

systemctl restart mergify

# Window expires automatically after 10 minutes

Summary

| Monitor | Target | What It Catches | |---|---|---| | Webhook HTTP | https://mergify.yourdomain.com/health | Service crash, FastAPI down | | TCP port | :3000 | Process down, port not listening | | SSL certificate | Mergify domain | Certificate expiry, GitHub webhook TLS failure | | GitHub API | api.github.com/zen | GitHub API reachability | | GitHub rate limit | Heartbeat URL | Rate limit exhaustion before API failures | | Merge queue | Heartbeat URL | Queue stuck, Mergify-GitHub connection lost | | CI signal | Heartbeat URL | CI pipeline stopped, webhook delivery stalled | | Config validation | /v1/repos/.../config | .mergify.yml syntax error, inactive config | | Backport jobs | Heartbeat URL | Backport worker stalled, hotfixes not backported |

Mergify sits at the most critical point in your development workflow: the moment code becomes production. When it's working, you trust the automation completely. When it breaks, that trust means the failure is often the last thing anyone checks. With Vigilmon watching Mergify's webhook service, GitHub API health, merge queue activity, and backport jobs, you get the early warning that keeps your automation trustworthy.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles