Automated Deployment Health Monitor

Monitors Vercel deployment status, error rates, and performance metrics with real-time alerts for failed deployments or performance degradation.

When to Use This Hook

Attach this hook when you need to:

• Automatically check deployment health after every build or deploy command to catch failures before they impact users
• Track deployment success rates over time and receive alerts when the rate drops below acceptable thresholds
• Get immediate session-start context about your latest deployment status so you know the current production state

Consider alternatives when:

• You use a deployment platform other than Vercel and need a platform-agnostic monitoring solution
• Your team already has comprehensive deployment monitoring through Datadog, PagerDuty, or similar observability tools

Quick Start

Configuration

Copy
name: automated-deployment-health-monitor
type: hook
trigger: PostToolUse, SessionStart
category: automation

Example Trigger

Copy
vercel deploy --prod
# Hook output:
# Deployment Health Monitor: Checking deployment status...

Example Output

Deployment Health Monitor: Analysis Complete
Recent deployment analysis (5 deployments):
State: READY | Created: 2026-03-15T10:23:00Z | URL: my-app-abc123.vercel.app
State: READY | Created: 2026-03-14T16:45:00Z | URL: my-app-def456.vercel.app
State: ERROR | Created: 2026-03-14T14:12:00Z | URL: N/A

Deployment Health Summary:
Successful: 4/5 (80%)
Failed: 1/5
In Progress: 0/5
Latest deployment: READY (14 minutes ago)
URL: https://my-app-abc123.vercel.app
Deployment health check completed

Core Concepts

Health Monitoring Overview

Aspect	Details
Platform	Vercel deployments via REST API v6
Authentication	Requires VERCEL_TOKEN and VERCEL_PROJECT_ID environment variables
Check Points	SessionStart for initial status, PostToolUse for deploy-related commands
Metrics Tracked	Success rate, failure count, build duration, deployment URL
Alert Threshold	Success rate below 80% triggers warning, below 50% triggers critical alert
History Depth	Analyzes the 5 most recent deployments for trend calculation

Monitoring Workflow

Trigger Event (SessionStart or Deploy Command)
    |
    v
[Verify VERCEL_TOKEN and VERCEL_PROJECT_ID set?]
    |                    |
   No --> [Skip]        Yes
                         |
                         v
            [Query Vercel API for recent deployments]
                         |
                         v
            [Parse deployment states: READY/ERROR/BUILDING]
                         |
                         v
            [Calculate success rate and trends]
                         |
                         v
            [Generate health report]
                         |
              +----------+----------+
              |          |          |
           >= 80%    50-79%      < 50%
           HEALTHY   WARNING   CRITICAL

Configuration

Parameter	Type	Default	Description
VERCEL_TOKEN	string	(required)	Vercel API authentication token obtained from vercel.com/account/tokens
VERCEL_PROJECT_ID	string	(required)	Project identifier found in the Vercel dashboard project settings
deployment_limit	integer	5	Number of recent deployments to analyze for health calculation
warning_threshold	integer	80	Success rate percentage below which a warning is triggered
critical_threshold	integer	50	Success rate percentage below which a critical alert with exit code 2 is triggered

Best Practices

1. Store tokens securely in environment variables - Never hardcode VERCEL_TOKEN or VERCEL_PROJECT_ID in hook configuration files. Use your shell profile, a .env file excluded from version control, or a secrets manager to inject these values into the environment safely.

2. Set up the SessionStart check for morning context - The session-start health check gives you immediate awareness of the production state when you begin work. If the last deployment failed overnight, you will know before writing new code, allowing you to prioritize the fix.

3. Adjust thresholds for your deployment frequency - Teams that deploy many times per day should use a higher warning threshold like 90%, while teams that deploy weekly can tolerate a lower threshold. Calibrate the percentages to match your team's deployment cadence and risk tolerance.

4. Use the troubleshooting output for triage - When failures are detected, the monitor outputs specific troubleshooting steps including checking the Vercel dashboard, reviewing recent code changes, and verifying environment variables. Follow these steps systematically rather than guessing at the root cause.

5. Monitor build queue depth during peak hours - The monitor tracks in-progress builds. If you consistently see multiple builds queued simultaneously, it may indicate that your team needs to coordinate deployments better or upgrade your Vercel plan for more concurrent builds.

Common Issues

1. Monitor reports all deployments as skipped - This occurs when VERCEL_TOKEN or VERCEL_PROJECT_ID environment variables are not set. Export both variables in your shell profile and restart your terminal session. Verify with echo $VERCEL_TOKEN to confirm they are available.

2. API rate limiting causes intermittent failures - The Vercel API has rate limits that may be exceeded if the hook fires frequently during rapid development sessions. The monitor silently handles API errors, but if you notice gaps in monitoring, reduce the deployment_limit or add a cooldown period between checks.

3. Stale deployment data after project migration - If you migrate to a new Vercel project, the old VERCEL_PROJECT_ID will return deployments for the previous project. Update the project ID immediately after migration to ensure the monitor tracks the correct deployment history.