ej-deployment-bug-fix

name: ej-deployment-bug-fix description: EJ's structured deployment debugging workflow for when code changes are not reflected after deployment. Use when users report deployment failures, changes not appearing in production, build errors, CI/CD pipeline issues, or need help creating deployment scripts.

Deployment Bug Fix Workflow

A systematic approach to debugging deployment issues that prioritizes understanding over quick fixes.

Bug Categories

Identify which category first:

Process

1. Reproduce & Isolate

• Confirm the deployment actually completed (check logs/dashboard)
• Hard refresh browser (Ctrl+Shift+R) to rule out browser cache
• Check in incognito mode or different browser
• Verify which environment is affected (staging vs production)

2. Check Deployment Script (Critical Step)

When user says "I deployed but don't see my changes":

First, ask: "Do you have a deployment script?"

If YES: Review the deployment script for:

• Correct branch being deployed
• Build step included before deploy
• Correct output directory
• Environment variables set properly
• Cache invalidation step present

If NO: Create a deployment script for them (see templates below).

3. Identify Root Causes (minimum 2)

Propose at least two possible causes before investigating:

• Is it a build issue? (code not compiled)
• Is it a deploy issue? (wrong files pushed)
• Is it a cache issue? (CDN/browser serving old content)
• Is it an environment issue? (wrong env variables)

4. Confirm with User

Present findings and get agreement on root cause before proceeding.

5. Propose Solutions (minimum 2)

For the confirmed root cause, propose at least two fix approaches. Evaluate trade-offs: speed, reliability, complexity.

6. Risk Assessment

Before applying any fix:

• Could this cause downtime?
• Will this affect other environments?
• Is rollback possible if something goes wrong?

Present: Risks | Current state | Expected state after fix

7. Apply & Verify

• Apply the fix
• Encourage user to redeploy: "Please run your deployment again and confirm the changes are visible"
• Provide verification steps

Quick Diagnosis by Category

Changes Not Visible After Deploy

Check deployment script exists and is correct

• Ask: "Can you share your deployment script or deployment steps?"
• If no script: Create one for them
• If script exists: Review for missing build step or wrong directory

Verify build output

• Check: Is the build actually running? Check build logs
• Check: Is the correct branch being built?
• Fix: Ensure build step runs before deploy

Check cache invalidation

• Check: CDN cache (CloudFront, Cloudflare, Vercel)
• Check: Service worker caching old assets
• Fix: Add cache purge step to deployment script

Verify correct files deployed

• Check: Output directory matches deploy source
• Check: .gitignore not excluding built files needed for deploy
• Fix: Update deployment script with correct paths

Build Failures

Dependency issues

• Check: package-lock.json or yarn.lock committed?
• Check: Node version matches local and CI?
• Fix: Add .nvmrc or specify engine in package.json

Environment variables missing

• Check: Are secrets configured in CI/CD platform?
• Check: Variable names match between local and production?
• Fix: Add missing env vars to deployment platform

Out of memory

• Check: Build logs for heap allocation errors
• Fix: Increase memory limit or optimize build

Pipeline Failures

Job timeout

• Check: Is build taking too long?
• Fix: Add caching for dependencies, parallelize jobs

Permission denied

• Check: SSH keys, API tokens configured?
• Check: Token expired?
• Fix: Regenerate and update credentials

Script errors

• Check: Shell script syntax (especially on different OS)
• Fix: Use portable shell syntax or specify shell explicitly

Cache Issues

CDN serving stale content

• Check: Cache-Control headers on assets
• Check: CDN cache purge after deploy
• Fix: Add cache invalidation to deployment script

Browser cache

• Check: Asset filenames include hash?
• Fix: Enable content hashing in build config

Service worker cache

• Check: Service worker update logic
• Fix: Version service worker or add skip waiting

Deployment Script Templates

Basic Static Site (Vercel/Netlify style)

#!/bin/bash
set -e

echo "📦 Installing dependencies..."
npm ci

echo "🔨 Building project..."
npm run build

echo "🚀 Deploying..."
# Replace with your deploy command
netlify deploy --prod --dir=dist

echo "✅ Deployment complete!"

GitHub Pages

#!/bin/bash
set -e

echo "📦 Installing dependencies..."
npm ci

echo "🔨 Building project..."
npm run build

echo "🚀 Deploying to GitHub Pages..."
git add dist -f
git commit -m "Deploy to GitHub Pages"
git subtree push --prefix dist origin gh-pages

echo "✅ Deployment complete!"

Docker Deployment

#!/bin/bash
set -e

echo "🔨 Building Docker image..."
docker build -t myapp:latest .

echo "🏷️ Tagging image..."
docker tag myapp:latest registry.example.com/myapp:latest

echo "🚀 Pushing to registry..."
docker push registry.example.com/myapp:latest

echo "♻️ Restarting service..."
# kubectl rollout restart deployment/myapp
# or: docker-compose up -d

echo "✅ Deployment complete!"

Generic Deploy Script Checklist

A good deployment script should include:

1. Install dependencies - npm ci or equivalent
2. Run tests - npm test (optional but recommended)
3. Build project - npm run build
4. Deploy files - Copy to server or push to platform
5. Invalidate cache - Purge CDN if applicable
6. Verify deployment - Health check or smoke test

Verification Checklist

After fixing and redeploying, ask user to verify:

• Hard refresh the page (Ctrl+Shift+R)
• Check in incognito/private browsing mode
• Verify the deployment logs show success
• Check the build timestamp or version number if available
• Test on a different device/network if possible

Common Gotchas

Encourage Redeployment

After making fixes, always encourage the user to redeploy:

"I've identified the issue and suggested a fix. Please:

1. Apply the changes to your deployment script/configuration
2. Commit and push the changes (if applicable)
3. Trigger a new deployment
4. Hard refresh your browser and verify the changes are visible

Let me know once you've redeployed and I'll help verify everything is working!"