tutorial

Monitoring Semantic Release with Vigilmon

Semantic Release automates your versioning and package publishing — but if the release pipeline breaks silently, no one knows a release was skipped. Here's how to monitor Semantic Release's CI integration, registry publishing, and changelog generation with Vigilmon.

Semantic Release eliminates manual version bumps and changelog maintenance by automating the entire release workflow — reading your commit history, determining the next semantic version, publishing to package registries, and creating GitHub releases. But that automation is only trustworthy when it actually runs. A CI step that silently fails, a package registry that times out, or a non-conventional commit that skips the release without notice can leave your users on a stale version without anyone on your team knowing. Vigilmon closes that observability gap by monitoring every layer of your Semantic Release pipeline.

What You'll Set Up

  • HTTP uptime monitor for the Semantic Release webhook server (when running in server mode)
  • Cron heartbeat for CI pipeline release job health
  • HTTP monitors for package registry connectivity (npm, PyPI, Docker Hub)
  • HTTP monitor for GitHub/GitLab release API connectivity
  • Heartbeat for monorepo per-package release job success

Prerequisites

  • Semantic Release configured in your CI/CD pipeline (GitHub Actions, GitLab CI, or Jenkins)
  • Optionally: Semantic Release running in server mode on port 3000 for webhook-triggered releases
  • A free Vigilmon account

Step 1: Monitor the Semantic Release Webhook Server (Server Mode)

When Semantic Release is deployed as an always-on service that triggers releases via webhook (rather than running ephemerally in CI), the webhook API server on port 3000 must stay available. Downtime means merge events that should trigger releases are silently dropped.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Semantic Release server URL: https://release.yourdomain.com (or http://your-server:3000).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

Add a health endpoint to your Semantic Release server configuration if not already present:

// server.js — minimal health endpoint alongside release webhook
const express = require('express');
const app = express();

app.get('/health', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() });
});

app.post('/webhook', async (req, res) => {
  // trigger semantic-release
});

If you run Semantic Release exclusively in CI (the most common pattern), skip this step and focus on Steps 2 through 5 instead.

Step 2: Heartbeat for CI Release Job Execution

The most common Semantic Release failure mode is silent: the CI step runs, finds no releasable commits (or fails early), and exits without publishing — leaving the team unaware that a release was expected but skipped.

Set up a Vigilmon cron heartbeat to confirm the release job is completing successfully:

  1. Click Add Monitor → Cron Heartbeat.
  2. Set the expected interval to your release cadence (e.g. 1440 minutes for daily releases, or 60 minutes if you release on every merge to main).
  3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_ID.

GitHub Actions

Add the heartbeat ping as the final step in your release job:

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Semantic Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

      - name: Ping Vigilmon heartbeat
        if: success()
        run: curl -s https://vigilmon.online/heartbeat/YOUR_ID

The if: success() condition ensures the heartbeat only pings when the release step completes without error. If semantic-release exits non-zero, the heartbeat is skipped and Vigilmon alerts.

GitLab CI

release:
  stage: release
  script:
    - npx semantic-release
    - curl -s https://vigilmon.online/heartbeat/YOUR_ID
  only:
    - main

Step 3: Monitor npm Registry Connectivity

If Semantic Release publishes to npm and the registry is unreachable or authentication fails, the publish step fails — but the version bump and GitHub release may have already been created, leaving the package at the old version in the registry while the git tag says otherwise.

Add an HTTP monitor for npm registry availability:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter https://registry.npmjs.org/.
  3. Set Check interval to 5 minutes.
  4. Click Save.

For private npm registries (Verdaccio, Nexus, Artifactory), monitor your registry's health endpoint instead:

https://your-registry.yourdomain.com/-/ping

To monitor npm token validity, add a lightweight check that exercises your publish credentials:

# Check if token can read package metadata (does not publish)
npm whoami --registry https://registry.npmjs.org

Run this as a periodic CI job and ping a separate Vigilmon heartbeat when it succeeds — alerting before a token expiry breaks a production release.

Step 4: Monitor PyPI Connectivity (Python Packages)

For Semantic Release workflows that publish to PyPI, add a connectivity monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter https://pypi.org/pypi/pip/json (a lightweight status probe that checks PyPI's JSON API).
  3. Set Check interval to 5 minutes.
  4. Click Save.

For private PyPI mirrors (devpi, Nexus), monitor your instance health endpoint:

https://pypi.yourdomain.com/

Step 5: Monitor GitHub/GitLab Release API Connectivity

Semantic Release creates git tags and GitHub/GitLab releases as part of every successful run. If the release API is unavailable or the token scope is insufficient, the publish step fails — often after the npm publish has already succeeded, leaving a published package with no corresponding GitHub release.

Add an HTTP monitor for the GitHub API:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter https://api.github.com/meta.
  3. Set Check interval to 5 minutes.
  4. Click Save.

For GitLab self-hosted, monitor your instance:

  1. Enter https://gitlab.yourdomain.com/-/health.
  2. Set Check interval to 5 minutes.
  3. Click Save.

Monitor GitHub token scope separately. Create a CI probe job that verifies your GITHUB_TOKEN can create releases:

# Verify token has repo scope for release creation
curl -s -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/repos/YOUR_ORG/YOUR_REPO \
  | jq '.permissions.push'
# Should return true

Step 6: Monitor Docker Hub Publishing (Docker Images)

For projects that publish Docker images via Semantic Release, add a monitor for Docker Hub availability:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Enter https://hub.docker.com/ or https://index.docker.io/v2/.
  3. Set Check interval to 5 minutes.
  4. Click Save.

For self-hosted Docker registries, monitor the registry's v2 API:

https://registry.yourdomain.com/v2/

A 200 or 401 response indicates the registry is up — 401 means authentication is required, which is expected behavior and confirms the registry is accepting connections.

Step 7: Monorepo Per-Package Release Heartbeats

For monorepos using Semantic Release with Lerna or pnpm workspaces, each package publishes independently. A single package failure can block the release of dependent packages without surfacing clearly in CI logs.

Set up one heartbeat per critical package:

  1. Click Add Monitor → Cron Heartbeat for each package.
  2. Set the expected interval to match your release cadence.
  3. Copy each package's heartbeat URL.

Add per-package heartbeat pings to your release scripts:

# .github/workflows/release.yml
jobs:
  release-core:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: cd packages/core && npx semantic-release
      - if: success()
        run: curl -s https://vigilmon.online/heartbeat/CORE_PACKAGE_ID

  release-cli:
    needs: release-core
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: cd packages/cli && npx semantic-release
      - if: success()
        run: curl -s https://vigilmon.online/heartbeat/CLI_PACKAGE_ID

This gives you per-package visibility — if release-core succeeds but release-cli fails, you know exactly where to look.

Step 8: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
  2. For CI release job heartbeats, alert on 1 missed beat — a skipped release that should have happened is a production issue.
  3. For registry availability monitors, set Consecutive failures before alert to 2 — brief transient failures are common on public registries.
  4. For GitHub API monitoring, set 2 failures before alerting.

Recommended alert routing:

| Monitor | Channel | Threshold | |---|---|---| | Release server (port 3000) | #releases | 2 failures | | CI job heartbeat | #releases | 1 missed beat | | npm registry | #dev-alerts | 2 failures | | PyPI | #dev-alerts | 2 failures | | GitHub API | #dev-alerts | 2 failures | | Docker Hub | #dev-alerts | 2 failures | | Per-package monorepo heartbeats | #releases | 1 missed beat |

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP server | https://release.yourdomain.com/health | Webhook server outage (server mode) | | Cron heartbeat | Release job heartbeat URL | Silent CI job failure or skipped release | | HTTP | npm registry | Publish failures due to registry outage | | HTTP | PyPI | Python package publish failures | | HTTP | GitHub/GitLab API | Release creation failures | | HTTP | Docker Hub / private registry | Docker image push failures | | Cron heartbeat | Per-package heartbeat URLs | Monorepo package release failures |

Semantic Release works best when it's invisible — every commit to main that deserves a release gets one, automatically, without manual intervention. Vigilmon ensures that automation stays invisible in the right way: you only hear about it when something goes wrong, not because you manually checked whether the pipeline ran.

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