/rollback-dev

description: Rollback {{DEV_MACHINE}} dev environment to previous Docker image
argument-hint: [commit-sha]
allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]

> **📋 TEMPLATE**: This command is a template. See "Customization Guide" below to adapt for your infrastructure.

Rollback the {{DEV_MACHINE}} dev environment to a previous Docker image version.

Workflow

1. Assess Current Situation

Get current problematic version:

# {{TICKET_PREFIX}}-445: Updated container name per Terminology Contract
ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker inspect {{PROJECT}}-dev-app | grep 'org.opencontainers.image.revision' | cut -d'\"' -f4"

Check current status:

curl -s http://{{REMOTE_HOST}}:3000/api/health 2>/dev/null || echo "Health check failed"

Document the issue for Linear ticket creation later.

2. List Available Rollback Targets

Show recent images on {{DEV_MACHINE}}:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker images {{REGISTRY}}/{{PROJECT_NAME}}/dev --format 'table {{.Tag}}\t{{.ID}}\t{{.CreatedAt}}'"

Cross-reference with git commits to show messages:

git log origin/dev -10 --oneline

3. Select Rollback Target

**If argument provided** (commit SHA like `e9722d4`):

• Use specified commit as rollback target
• Verify image exists with that SHA tag

**If no argument provided**:

• Display last 5 available images with commit messages
• Recommend previous stable version (before current)
• Ask user to confirm selection

Default behavior: Select image before current (most common rollback scenario)

4. Pull Rollback Image

Pull the specific version from registry:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker pull {{REGISTRY}}/{{PROJECT_NAME}}/dev:dev-{target-sha}"

If image not in registry (old version pruned), use local cached image.

5. Update Configuration

Create backup of current config:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && cp docker-compose.dev.yml docker-compose.dev.yml.backup.$(date +%Y%m%d_%H%M%S)"

Update docker-compose.dev.yml to use specific image tag:

# From: image: {{REGISTRY}}/{{PROJECT_NAME}}/dev:latest
# To:   image: {{REGISTRY}}/{{PROJECT_NAME}}/dev:dev-{target-sha}

Use SSH + sed for inline replacement:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && sed -i 's|{{REGISTRY}}/{{PROJECT_NAME}}/dev:latest|{{REGISTRY}}/{{PROJECT_NAME}}/dev:dev-{target-sha}|g' docker-compose.dev.yml"

6. Restart Services

Restart with rollback image:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && ./scripts/dev-docker.sh restart"

Monitor startup:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && ./scripts/dev-docker.sh logs --tail 50"

7. Verify Rollback Success

Check services started:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker ps --filter name={{PROJECT}}"

Verify health endpoint:

curl -s http://{{REMOTE_HOST}}:3000/api/health | jq

Confirm correct commit SHA:

# {{TICKET_PREFIX}}-445: Updated container name per Terminology Contract
ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker inspect {{PROJECT}}-dev-app | grep 'org.opencontainers.image.revision' | cut -d'\"' -f4"

8. Post-Rollback Actions

**If rollback successful**:

• Keep rollback configuration in place
• Create Linear ticket documenting the issue with broken version
• Include error logs and health check failures
• Tag ticket with `bug` and `deployment-rollback` labels
• Notify team via Slack about rollback

**If rollback still has issues**:

• Try rolling back to an even older version
• Check if issue is environmental (database, Redis, etc.)
• Escalate to team for investigation

9. Rollback Report

Provide comprehensive rollback summary:

⏮️  {{DEV_MACHINE}} Dev Environment Rollback

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Problem Detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Version:  3a49b85 - feat(ci): add Slack notifications [{{TICKET_PREFIX}}-350]
Issue:    Health check failing / Services crashing
Time:     Deployed 5 minutes ago

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rollback Target
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Selected: e9722d4 - style(docs): apply markdown linting fixes [{{TICKET_PREFIX}}-347]
Reason:   Last known stable version
Age:      7 hours ago

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Rollback Progress
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[14:30:00] Backup config... ✅ docker-compose.dev.yml.backup.20251011_143000
[14:30:05] Pull rollback image... ✅ dev-e9722d4 (45s)
[14:30:50] Update config... ✅ Set to dev-e9722d4
[14:30:55] Restart services... ✅ Complete (28s)
[14:31:23] Health check... ✅ Passed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Post-Rollback Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Running:  e9722d4 - style(docs): apply markdown linting fixes [{{TICKET_PREFIX}}-347]
Status:   ✅ Healthy
URL:      http://{{REMOTE_HOST}}:3000
Duration: 1m 23s

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Rollback Complete - Environment Restored
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Next steps:
• Create Linear ticket for broken version (3a49b85)
• Include error logs and symptoms
• Investigate root cause before redeploying
• Keep this version until fix is verified

To return to latest (when fixed):
  /remote-deploy

10. Restore to Latest (When Fixed)

When issue is resolved and new build is ready, restore to latest:

# Restore docker-compose.dev.yml to use :latest tag
ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && sed -i 's|{{REGISTRY}}/{{PROJECT_NAME}}/dev:dev-[a-f0-9]*|{{REGISTRY}}/{{PROJECT_NAME}}/dev:latest|g' docker-compose.dev.yml"

# Then deploy normally
/remote-deploy

Error Handling

Image No