/remote-rollback

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

Rollback the remote development environment to a previous Docker image version.

> **📋 TEMPLATE**: This command is a template. Replace placeholders with your infrastructure values before use. See the **Customization Guide** at the bottom.

Workflow

1. Assess Current Situation

Get current problematic version:

# ┌─────────────────────────────────────────────────────────┐
# │ CUSTOMIZE: Replace with your SSH and container settings │
# └─────────────────────────────────────────────────────────┘
ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker inspect {{APP_CONTAINER_STAGING}} 2>/dev/null | grep 'org.opencontainers.image.revision' | cut -d'\"' -f4 || docker inspect {{APP_CONTAINER_DEV}} | grep 'org.opencontainers.image.revision' | cut -d'\"' -f4"

Check current status:

curl -s http://{{REMOTE_HOST}}:{{DEV_PORT}}/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 remote host:

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

Cross-reference with git commits to show messages:

git log origin/{{MAIN_BRANCH}} -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}}/{{IMAGE_NAME}}:{{TAG_PREFIX}}-{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 {{COMPOSE_FILE}} {{COMPOSE_FILE}}.backup.$(date +%Y%m%d_%H%M%S)"

Update docker-compose file to use specific image tag:

# From: image: {{REGISTRY}}/{{IMAGE_NAME}}:latest
# To:   image: {{REGISTRY}}/{{IMAGE_NAME}}:{{TAG_PREFIX}}-{target-sha}

Use SSH + sed for inline replacement:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && sed -i 's|{{REGISTRY}}/{{IMAGE_NAME}}:latest|{{REGISTRY}}/{{IMAGE_NAME}}:{{TAG_PREFIX}}-{target-sha}|g' {{COMPOSE_FILE}}"

6. Restart Services

Restart with rollback image:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && {{DOCKER_SCRIPT}} restart"

Monitor startup:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "cd {{PROJECT_PATH}} && {{DOCKER_SCRIPT}} logs --tail 50"

7. Verify Rollback Success

Check services started:

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

Verify health endpoint:

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

Confirm correct commit SHA:

ssh -i {{SSH_KEY_PATH}} {{REMOTE_USER}}@{{REMOTE_HOST}} "docker inspect {{APP_CONTAINER_STAGING}} 2>/dev/null | grep 'org.opencontainers.image.revision' | cut -d'\"' -f4 || docker inspect {{APP_CONTAINER_DEV}} | 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:

⏮️  Remote 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... ✅ {{COMPOSE_FILE}}.backup.20251011_143000
[14:30:05] Pull rollback image... ✅ {{TAG_PREFIX}}-e9722d4 (45s)
[14:30:50] Update config... ✅ Set to {{TAG_PREFIX}}-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}}:{{DEV_PORT}}
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:

# Res