How to Monitor Your CircleCI Workflows with Vigilmon

CircleCI is one of the most popular cloud CI/CD platforms — fast, developer-friendly, and deeply integrated with GitHub. But CI/CD pipelines are production infrastructure: a stuck pipeline means delayed deployments, unmerged security patches, and blocked releases. And CircleCI itself can experience outages that silently queue your builds.

This guide shows you how to monitor CircleCI workflows and scheduled pipelines with Vigilmon.

---

What Can Go Wrong with CircleCI

• CircleCI service outages — the platform itself is down; builds queue indefinitely
• Scheduled pipeline failures — nightly builds that fail silently (no one reviews nightly build results)
• Resource class exhaustion — your org runs out of compute credits or concurrency limits hit
• Critical workflow consistently failing — tests broken, deployment pipeline dead

---

Step 1: Monitor CircleCI Service Status via API

CircleCI exposes its own status page and API. Create a health proxy:

const express = require('express');
const axios = require('axios');

const app = express();
const CIRCLE_TOKEN = process.env.CIRCLECI_API_TOKEN;

app.get('/health/circleci', async (req, res) => {
  try {
    // Check CircleCI API is responsive
    const response = await axios.get(
      'https://circleci.com/api/v2/me',
      {
        headers: { 'Circle-Token': CIRCLE_TOKEN },
        timeout: 5000
      }
    );

    res.json({ 
      status: 'ok',
      user: response.data.login,
      platform: 'circleci'
    });
  } catch (err) {
    if (err.response?.status === 401) {
      // API is up but token is invalid - still operational
      return res.status(503).json({ 
        status: 'auth_error',
        message: 'Invalid API token'
      });
    }
    res.status(503).json({ 
      status: 'unreachable',
      message: err.message 
    });
  }
});

---

Step 2: Monitor Pipeline Workflow Status

Check if your critical workflows are succeeding:

const VCS_TYPE = 'github';
const ORG = 'your-org';
const REPO = 'your-repo';
const BRANCH = 'main';

app.get('/health/circleci/pipeline', async (req, res) => {
  try {
    // Get recent pipelines for main branch
    const pipelinesRes = await axios.get(
      `https://circleci.com/api/v2/project/${VCS_TYPE}/${ORG}/${REPO}/pipeline?branch=${BRANCH}`,
      {
        headers: { 'Circle-Token': CIRCLE_TOKEN },
        timeout: 8000
      }
    );

    const pipelines = pipelinesRes.data.items.slice(0, 5); // Last 5 pipelines

    if (pipelines.length === 0) {
      return res.json({ status: 'ok', message: 'No recent pipelines' });
    }

    // Check the most recent pipeline's workflows
    const latestPipeline = pipelines[0];
    const workflowsRes = await axios.get(
      `https://circleci.com/api/v2/pipeline/${latestPipeline.id}/workflow`,
      { headers: { 'Circle-Token': CIRCLE_TOKEN }, timeout: 5000 }
    );

    const workflows = workflowsRes.data.items;
    const failedWorkflows = workflows.filter(w => w.status === 'failed');
    const runningWorkflows = workflows.filter(w => 
      ['running', 'on_hold'].includes(w.status)
    );

    if (failedWorkflows.length > 0 && runningWorkflows.length === 0) {
      return res.status(503).json({
        status: 'pipeline_failed',
        branch: BRANCH,
        failed_workflows: failedWorkflows.map(w => w.name)
      });
    }

    res.json({
      status: 'ok',
      latest_pipeline: latestPipeline.number,
      workflow_statuses: workflows.map(w => ({ name: w.name, status: w.status }))
    });
  } catch (err) {
    res.status(503).json({ status: 'error', message: err.message });
  }
});

app.listen(3000);

---

Step 3: Add Vigilmon HTTP Monitors

1. Log in to vigilmon.online → Add Monitor
2. Monitor 1 — CircleCI API:
   • URL: https://your-app.com/health/circleci
   • Alert if: Status != 200
3. Monitor 2 — Pipeline health:
   • URL: https://your-app.com/health/circleci/pipeline
   • Alert if: Status != 200
4. Interval: 300 seconds (5 minutes — pipeline checks don't need 60s resolution)

---

Step 4: Heartbeat for Scheduled Pipelines

For nightly builds, data processing jobs, or any scheduled workflow, add a Vigilmon heartbeat to the final job:

# .circleci/config.yml
version: 2.1

workflows:
  nightly-build:
    triggers:
      - schedule:
          cron: "0 2 * * *"  # 2 AM UTC
          filters:
            branches:
              only: main
    jobs:
      - build
      - test:
          requires: [build]
      - notify-vigilmon:
          requires: [test]

jobs:
  notify-vigilmon:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          name: Ping Vigilmon heartbeat
          command: curl -sf https://hb.vigilmon.online/YOUR-HEARTBEAT-ID

In Vigilmon, configure the heartbeat monitor to alert if no ping is received in 25 hours — catching any missed nightly run.

---

CircleCI Monitoring Coverage Table

Monitor	What It Checks	Alert Condition
API health	CircleCI API reachable	Unreachable
Pipeline status	Main branch workflows	Failed workflows
Nightly build	Scheduled pipeline	Build missed

---

Common CircleCI Failure Patterns

CircleCI platform outage: CircleCI experienced outages in 2023 and 2024. Builds queued for hours silently. API health monitor catches this by attempting CircleCI API calls — if unreachable, you know immediately.

Nightly integration tests silently failing: A database migration broke integration tests. Nightly builds failed for 3 consecutive nights before a developer noticed. Heartbeat monitor would have fired on the first miss.

Critical dependency updated: A transitive npm dependency updated and broke the test suite. The main branch build began consistently failing. Pipeline health monitor fires when 2+ consecutive builds fail.

---

Conclusion

CI/CD pipelines are production infrastructure. Broken pipelines mean delayed fixes, security patches stuck in review, and blocked releases. Vigilmon makes it easy to monitor CircleCI API health, pipeline success rates, and scheduled workflow execution.

Start monitoring your CircleCI workflows free at vigilmon.online