Hotfix Deploy Runner

Execute emergency hotfix deployments with built-in safety checks and rollback procedures.

When to Use This Command

Run this command when you need to:

• Deploy a critical production fix that cannot wait for the normal release cycle
• Execute a tested hotfix with automated staging validation before production push
• Perform an emergency deployment with pre-configured rollback safeguards

Consider alternatives when:

• The issue is not customer-facing and can follow the standard release pipeline
• You need a full rollback to a previous version rather than deploying a forward fix

Quick Start

Configuration

Copy
name: hotfix-deploy-runner
type: command
category: deployment

Example Invocation

Copy
claude command:run hotfix-deploy-runner --branch hotfix/auth-bypass --target production

Example Output

Hotfix Deployment: hotfix/auth-bypass
Current production: v2.14.3 (tag)
Hotfix base: v2.14.3

Pre-flight checks:
  [OK] Branch exists and is clean
  [OK] Tests pass (47/47)
  [OK] Security scan clear
  [OK] Database migrations: none

Staging deployment:
  [OK] Deployed to staging (v2.14.4-rc.1)
  [OK] Smoke tests pass (12/12)
  [OK] Health check: 200 OK

Production deployment:
  [OK] Tagged v2.14.4
  [OK] Rolling deploy started (3 pods)
  [OK] Pod 1/3 healthy
  [OK] Pod 2/3 healthy
  [OK] Pod 3/3 healthy

Post-deploy validation:
  [OK] Error rate: 0.02% (baseline: 0.03%)
  [OK] p99 latency: 180ms (baseline: 195ms)

Hotfix v2.14.4 deployed successfully.
Rollback command: claude command:run rollback-deploy-auto --version v2.14.3

Core Concepts

Emergency Deployment Overview

Aspect	Details
Branch Strategy	Hotfix branch from latest production tag, not from main
Testing Scope	Focused test suite covering the fix plus critical path smoke tests
Deployment Mode	Rolling update with health-gate between pod batches
Rollback Plan	Automatic revert if error rate exceeds threshold within 10 minutes
Communication	Stakeholder notifications at each deployment phase

Hotfix Deployment Workflow

  Incident Detected
        |
        v
  +------------------+
  | Create Branch    |---> git checkout -b hotfix/xxx tags/vN.N.N
  +------------------+
        |
        v
  +------------------+
  | Apply Fix + Test |---> Minimal change, focused tests
  +------------------+
        |
        v
  +------------------+
  | Stage & Validate |---> Deploy to staging, run smoke tests
  +------------------+
        |
        v
  +------------------+
  | Production Deploy|---> Rolling deploy with health gates
  +------------------+
        |
        v
  +------------------+
  | Monitor & Merge  |---> Watch metrics, merge back to main
  +------------------+

Configuration

Parameter	Type	Default	Description
branch	string	required	Hotfix branch name to deploy
target	string	production	Target environment: staging or production
skip_staging	boolean	false	Skip staging validation (use only in dire emergencies)
rollback_threshold	float	5.0	Error rate percentage that triggers automatic rollback
notify	string	slack	Notification channel for deployment status updates

Best Practices

1. Keep Changes Minimal - A hotfix should contain only the lines necessary to resolve the incident. Resist the temptation to refactor or improve adjacent code, as every extra change increases deployment risk.

2. Always Validate on Staging First - Even under time pressure, deploy to staging and run smoke tests. The few minutes spent catching a broken fix in staging prevents a second incident in production.

3. Tag Before and After - Tag the current production state before deploying the hotfix. This creates a clear rollback target and an audit trail of exactly what changed and when.

4. Merge Back to Main Immediately - After a successful hotfix deployment, merge the hotfix branch into main and delete the branch. Orphaned hotfix branches cause drift and merge conflicts later.

5. Document the Incident - Record the timeline, root cause, fix applied, and lessons learned. Post-incident documentation prevents recurring issues and improves future response times.

Common Issues

1. Hotfix Branch Has Merge Conflicts - The hotfix branch diverged from main. Cherry-pick the fix commit onto a fresh branch from the production tag instead of trying to resolve conflicts under pressure.

2. Staging Tests Pass But Production Fails - Environment-specific configuration differences. Verify environment variables, database schemas, and external service endpoints match between staging and production.

3. Rollback Triggered Unexpectedly - The error rate threshold was too aggressive for normal variance. Adjust the rollback_threshold and monitoring window, or use a percentage-over-baseline metric instead of an absolute threshold.