deploy-watch

Deploy Watch

Monitor the Vercel deployment for the current branch. If it fails, automatically diagnose the build error, fix the code, push, and re-monitor until the deploy succeeds.

When to Use

• After git push when you want to ensure the Vercel deploy passes
• When you know a deploy has failed and want to auto-fix it
• The PostToolUse hook will remind you to run this after every git push

Prerequisites

• gh CLI authenticated (for GitHub Deployments API)
• Git repo with Vercel integration (deploys triggered by push)
• Optional: Vercel CLI (npx vercel) for richer build logs

Workflow

Step 1: Detect repo and deployment

Determine the GitHub repo from the git remote, then find the deployment for HEAD:

# Extract owner/repo from git remote
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
REPO=$(echo "$REMOTE_URL" | sed -E 's|.*github\.com[:/]([^/]+/[^/.]+)(\.git)?$|\1|')
SHA=$(git rev-parse HEAD)
SHORT_SHA="${SHA:0:7}"
BRANCH=$(git branch --show-current)

Find the deployment:

gh api "repos/$REPO/deployments?sha=$SHA&per_page=1" --jq '.[0] | {id, environment, created_at}'

If no deployment exists yet, wait 10 seconds and retry up to 3 times. Vercel typically creates the deployment within seconds of the push.

Step 2: Poll for completion

Poll the deployment status every 15 seconds, up to 10 minutes:

DEPLOY_ID=<from step 1>
gh api "repos/$REPO/deployments/$DEPLOY_ID/statuses" --jq '.[0] | {state, description, target_url}'

States:

• pending / in_progress / queued — keep polling
• success — report the preview URL and stop. Done!
• failure / error — go to Step 3

Report progress concisely every 2-3 polls: "Deploy in progress... (45s)" — don't flood the conversation.

Step 3: Diagnose the failure

On failure, get build logs using this priority order:

Option A — Local build reproduction (fastest, try first):

pnpm build 2>&1 | tail -50

If the local build reproduces the error, you have the full error output. Skip to Step 4.

Option B — Vercel CLI (if installed): The deployment status description field often contains a vercel inspect command:

npx vercel inspect <deployment-url> --logs 2>&1 | tail -80

Option C — GitHub check runs:

gh api "repos/$REPO/commits/$SHA/check-runs" --jq '.check_runs[] | select(.conclusion != "success") | {name, conclusion, output: .output}'

Option D — Vercel deployment page: Open the target_url from the deployment status — the build logs are visible there. Report the URL to the user if you can't get logs programmatically.

Step 4: Fix the error

1. Read the error output carefully. Identify the failing file(s) and line number(s).
2. Read the relevant source file(s).
3. Make the minimum change to resolve the build error. Common fixes:
   • TypeScript errors: type mismatches, missing imports, unused variables
   • Module resolution: missing dependencies, wrong import paths
   • Next.js: dynamic/static conflicts, middleware issues, missing env vars
4. Run pnpm build locally to verify the fix compiles.
5. If the local build passes:

git add <fixed-files>
git commit -m "fix: resolve Vercel build error — <brief description>

Co-Authored-By: Claude <tool-use> <noreply@anthropic.com>"
git push

Step 5: Re-monitor

After pushing the fix, go back to Step 1 with the new SHA. Continue the loop.

Guardrails

• Max 3 fix attempts. If the deploy still fails after 3 cycles, stop and report to the user. The error may need human judgment.
• Don't fix platform issues. If the error is about missing env vars, Vercel configuration, or infrastructure problems (not code), report it and stop. Suggest the user check with /vercel:env or the Vercel dashboard.
• Don't introduce regressions. Each fix must be minimal and targeted. Always run pnpm build locally before pushing.
• Separate commits. Each fix gets its own commit with a descriptive message, not squashed into the feature commit.
• Run tests if available. After fixing, run pnpm test if the project has tests. Don't push if tests fail.

Success Output

When the deploy succeeds, report:

Deploy successful!
  SHA: <short-sha>
  Branch: <branch>
  Preview: <target-url>
  Fix attempts: <n>

Error Output

When giving up after max attempts:

Deploy still failing after 3 fix attempts.
  SHA: <short-sha>
  Last error: <summary>
  Suggestion: <what to check manually>