Monitoring GoCD with Vigilmon: Server Health, Agent Connectivity, Pipeline API, Build Heartbeats & SSL Alerts

GoCD is an open-source continuous delivery server from Thoughtworks designed for complex deployment pipelines with first-class support for fan-in/fan-out workflows and pipeline dependencies. When you self-host GoCD, you own the server uptime — and when the GoCD server goes down or its agents disconnect, pipelines queue silently and releases stall. Vigilmon provides the external monitoring layer: server health checks, agent connectivity heartbeats, pipeline API validation, build completion signals, and SSL certificate alerts.

What You'll Build

• An HTTP monitor for the GoCD server dashboard
• A health check via GoCD's /go/api/v1/health endpoint
• A pipeline API check confirming the server is serving requests
• An agent connectivity heartbeat to catch disconnected agents
• A build completion heartbeat for end-to-end CD verification
• SSL certificate expiry alerts

Prerequisites

• GoCD server installed and running (standalone or Docker)
• At least one GoCD agent registered and connected
• A domain configured for your GoCD server with HTTPS
• A free account at vigilmon.online

Step 1: Monitor the GoCD Dashboard

The GoCD dashboard is the primary interface for viewing pipeline status, stage results, and deployment progress. A down dashboard means your team loses visibility into all delivery pipelines:

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://gocd.yourdomain.com/go/pipelines
3. Check interval: 120 seconds.
4. Expected status: 200.
5. Label: GoCD Dashboard
6. Click Save.

GoCD's dashboard path is /go/pipelines. A 200 response confirms the GoCD server process is alive, the database connection is healthy, and your reverse proxy is routing correctly.

Step 2: Check the GoCD Health API

GoCD exposes a dedicated health endpoint at /go/api/v1/health that returns a JSON array of health indicators including database connectivity and background worker status:

1. Add Monitor → HTTP.
2. URL: https://gocd.yourdomain.com/go/api/v1/health
3. Check interval: 60 seconds.
4. Expected status: 200.
5. Label: GoCD Health API
6. Click Save.

# Verify the health endpoint manually
curl -s https://gocd.yourdomain.com/go/api/v1/health | python3 -m json.tool
# Returns: [{"message":"Everything looks good.","detail":"..."}]

The health API validates internal GoCD subsystems — database, configuration repository, and background workers. A non-200 response or error body signals a subsystem failure that may not yet show up on the dashboard.

Step 3: Monitor the Pipeline Configuration API

GoCD's REST API drives the Go CLI, pipeline triggers, and external integrations. Monitor it with a periodic script that lists pipelines and confirms the API layer is responsive:

#!/bin/bash
# /etc/cron.d/gocd-api-check — runs every 5 minutes

STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -u "YOUR_USER:YOUR_PASSWORD" \
  -H "Accept: application/vnd.go.cd.v1+json" \
  https://gocd.yourdomain.com/go/api/config/pipeline_groups)

if [ "$STATUS" = "200" ]; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-API-HEARTBEAT-ID
fi

In Vigilmon:

1. Add Monitor → Heartbeat.
2. Expected interval: 5 minutes.
3. Grace period: 15 minutes.
4. Label: GoCD Pipeline API

The pipeline groups endpoint requires authentication and exercises the GoCD configuration database. If GoCD's XML or JSON config fails to parse after an upgrade, this endpoint returns an error while the dashboard may still partially render.

Step 4: Agent Connectivity Heartbeat

GoCD agents are separate processes that execute pipeline jobs. A disconnected or disabled agent means jobs queue indefinitely. Monitor agent health via the GoCD API:

#!/bin/bash
# /etc/cron.d/gocd-agents — runs every 5 minutes

IDLE_OR_BUILDING=$(curl -s \
  -u "YOUR_USER:YOUR_PASSWORD" \
  -H "Accept: application/vnd.go.cd.v2+json" \
  https://gocd.yourdomain.com/go/api/agents \
  | python3 -c "
import sys, json
agents = json.load(sys.stdin).get('_embedded', {}).get('agents', [])
ok = [a for a in agents if a.get('agent_state') in ('Idle', 'Building')]
print(len(ok))
" 2>/dev/null || echo "0")

if [ "${IDLE_OR_BUILDING:-0}" -ge 1 ] 2>/dev/null; then
  curl -fsS -X POST https://vigilmon.online/api/heartbeat/YOUR-AGENT-HEARTBEAT-ID
fi

In Vigilmon:

1. Add Monitor → Heartbeat.
2. Expected interval: 5 minutes.
3. Grace period: 15 minutes.
4. Label: GoCD Agent Connectivity

The script checks that at least one agent reports an Idle or Building state. LostContact, Missing, or Disabled agents do not count. If all agents drop, the heartbeat stops within the grace period.

Step 5: SSL Certificate Alerts

GoCD uses HTTPS for all web sessions, API calls, and agent-to-server communication. GoCD agents establish a TLS connection to the server — an expired certificate breaks agent registration and all job dispatching:

1. Add Monitor → SSL Certificate.
2. Domain: gocd.yourdomain.com
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days.
5. Click Save.

GoCD ships with a built-in self-signed certificate by default. If you're using your own certificate via a reverse proxy, the 30-day threshold gives you time to renew before agents begin rejecting the server's certificate.

Step 6: Build Completion Heartbeat

Add a Vigilmon heartbeat ping as a final step in a critical GoCD pipeline to verify end-to-end delivery — not just that GoCD is running, but that it's completing successful builds:

<!-- In your GoCD pipeline configuration (config.xml or via API) -->
<pipeline name="main-delivery">
  <stage name="build">
    <jobs>
      <job name="compile-and-test">
        <tasks>
          <exec command="npm">
            <arg>ci</arg>
          </exec>
          <exec command="npm">
            <arg>test</arg>
          </exec>
        </tasks>
      </job>
    </jobs>
  </stage>

  <stage name="notify">
    <jobs>
      <job name="vigilmon-heartbeat">
        <tasks>
          <exec command="curl">
            <arg>-fsS</arg>
            <arg>-X</arg>
            <arg>POST</arg>
            <arg>https://vigilmon.online/api/heartbeat/YOUR-BUILD-HEARTBEAT-ID</arg>
          </exec>
        </tasks>
      </job>
    </jobs>
  </stage>
</pipeline>

In Vigilmon:

1. Add Monitor → Heartbeat.
2. Expected interval: Match your pipeline trigger frequency (e.g., 60 minutes).
3. Grace period: 30 minutes.
4. Label: GoCD Build Completion

The notify stage only runs after all prior stages succeed. If the build stage fails, or if GoCD stops scheduling pipelines, the heartbeat goes silent and Vigilmon alerts you.

Step 7: Server Port and Process Check

GoCD listens on port 8153 (HTTP) and 8154 (HTTPS) by default, though these are often placed behind a reverse proxy. Monitor the exposed port directly:

1. Add Monitor → TCP.
2. Host: gocd.yourdomain.com, Port: 443.
3. Check interval: 60 seconds.
4. Label: GoCD Server Port
5. Click Save.

If using GoCD's native ports without a reverse proxy:

1. Host: gocd.yourdomain.com, Port: 8153.
2. Label: GoCD HTTP Port

A TCP failure before the HTTP monitor trips distinguishes a network-level failure from an application-level one — useful for triage when the GoCD process itself is running but unreachable.

Common GoCD Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | GoCD server process crash | Dashboard and health API monitors fire within 60 s | | Database connection failure | Health API returns error body | | All agents disconnect | Agent heartbeat stops within grace period | | Pipeline queue stalls | Build completion heartbeat stops | | SSL certificate expires | SSL monitor alerts at 30 days; agents reject server cert | | Config XML parse failure | Pipeline API heartbeat stops | | Reverse proxy misconfiguration | TCP check fires before HTTP monitors | | Agent-to-server TLS broken | Agent heartbeat stops; jobs queue indefinitely | | Builds consistently failing | Build completion heartbeat goes silent | | Port 8153/8154 unreachable | TCP monitors fire |

Self-hosting GoCD gives you sophisticated pipeline modeling — value stream maps, pipeline dependencies, and fan-in/fan-out — without per-seat licensing costs. Vigilmon ensures those pipelines stay running: watching the server, API layer, agent pool, build completion, and SSL certificate simultaneously so you know the moment something breaks before a release is blocked.

Start monitoring GoCD in under 5 minutes — register free at vigilmon.online.