Sentinel Vercel Guard

Guards against risky Vercel deployment operations by validating environment, branch, and configuration before deployment commands execute.

When to Use This Hook

Attach this hook when you need to:

• Prevent accidental production deployments from non-release branches by enforcing branch-based deployment policies
• Validate that required environment variables are configured before allowing deployment commands to proceed
• Block deployments when the local codebase has uncommitted changes or is out of sync with the remote branch

Consider alternatives when:

• Your Vercel project has branch protection rules configured at the platform level that already enforce deployment policies
• You use a CI/CD pipeline that handles deployment gating and does not allow local deployment commands

Quick Start

Configuration

Copy
name: sentinel-vercel-guard
type: hook
trigger: PreToolUse
category: automation

Example Trigger

Copy
vercel deploy --prod
# Guard intercepts:
# Sentinel: Validating deployment prerequisites...

Example Output

Sentinel Vercel Guard: Pre-deployment Validation
Current Branch: feature/dark-mode
Target: Production (--prod flag detected)
Branch Policy: BLOCKED - production deploys require main branch
Uncommitted Changes: 0
Remote Sync: Up to date
Environment Variables:
  VERCEL_TOKEN: Set
  VERCEL_PROJECT_ID: Set
  DATABASE_URL: Set
  API_KEY: Set
Decision: BLOCK - switch to main branch for production deployment

Core Concepts

Deployment Guard Overview

Aspect	Details
Trigger Point	PreToolUse on Bash commands matching vercel deploy patterns
Branch Validation	Checks current git branch against allowed deployment branches
Environment Check	Verifies required environment variables are set before deployment
Git State Check	Detects uncommitted changes and remote sync status
Production Flag	Detects --prod flag to apply stricter production deployment rules
Block Behavior	Returns exit code 2 to prevent command execution when policies fail

Guard Validation Workflow

PreToolUse (Bash with vercel deploy)
    |
    v
[Detect --prod flag?]
    |          |
   No         Yes (stricter rules)
    |          |
    v          v
[Standard]  [Production policy check]
    |          |
    v          v
[Check current git branch against allowed list]
    |
    v
[Check for uncommitted changes]
    |
    v
[Check remote sync status]
    |
    v
[Verify required environment variables]
    |
    v
[All checks pass?]
    |          |
   No         Yes
    |          |
 BLOCK       ALLOW
(exit 2)   (proceed)

Configuration

Parameter	Type	Default	Description
production_branches	string	main|master	Pipe-separated list of branches allowed for production deployments
require_clean_tree	boolean	true	Whether to block deployment when uncommitted changes exist
require_remote_sync	boolean	true	Whether to block deployment when the local branch is ahead of remote
required_env_vars	string	VERCEL_TOKEN	Comma-separated list of environment variables that must be set
allow_preview_any_branch	boolean	true	Whether to allow preview deployments from any branch without restrictions

Best Practices

1. Enforce branch policies strictly for production - Configure production_branches to only include your release branches. This single guard prevents the most common deployment accident: pushing an unfinished feature branch to production.

2. Allow flexible preview deployments - Set allow_preview_any_branch to true so developers can deploy preview environments from any branch for testing. This encourages early deployment testing without compromising production stability.

3. Include critical environment variables in the check list - Add project-specific variables like DATABASE_URL and API_KEY to the required_env_vars list. Missing environment variables are a common cause of deployment failures that are easily prevented with a pre-flight check.

4. Require remote sync for team coordination - When require_remote_sync is enabled, the guard prevents deploying code that has not been pushed. This ensures that deployments are reproducible from the remote repository and that team members can trace deployed code to specific commits.

5. Document bypass procedures for emergencies - Establish a documented process for bypassing the guard during emergency hotfixes. The guard can be temporarily disabled by unsetting a trigger variable, but this should require explicit team communication.

Common Issues

1. Guard blocks legitimate production deployments - If the current branch is named differently than expected (e.g., release/v2.0 instead of main), the guard will block the deployment. Add your release branch naming pattern to the production_branches configuration.

2. Remote sync check fails on new branches - Newly created local branches that have not been pushed to remote will fail the sync check. Push the branch with git push -u origin <branch> before deploying, or disable require_remote_sync for preview deployments.

3. Environment variable check is too strict - If the required variables list includes variables only needed in specific environments, the guard may block deployments unnecessarily. Use environment-specific variable lists or make certain variables optional for preview deployments.