claude-plugins/infraestrutura/skills/easypanel-rollback/SKILL.md

---
name: easypanel-rollback
description: Rollback EasyPanel deployments to previous versions via API oficial. Safely reverts to
  last working deployment. Use when user mentions "easypanel rollback", "reverter
  deploy", "rollback deployment", "previous version", "desfazer deploy".
author: Descomplicar® Crescimento Digital
version: 2.0.0
quality_score: 70
user_invocable: true
desk_task: TBD
allowed-tools: Task
dependencies:
  - easypanel-api
---

# EasyPanel Rollback

Rollback rápido e seguro para versões anteriores estáveis.

## Quando Usar

- Deploy falhou (health checks fail)
- Aplicação com erros em produção
- Rollback urgente necessário
- Testar versão anterior
- Recovery após incidente

## Sintaxe

```bash
/easypanel-rollback <service-name> [--to-version <version>] [--auto]
```

## Exemplos

```bash
# Rollback para versão anterior imediata
/easypanel-rollback dashboard-api

# Rollback para tag específica
/easypanel-rollback dashboard-api --to-version v1.2.5

# Rollback automático (sem confirmação)
/easypanel-rollback dashboard-api --auto
```

## Workflow Completo

### 1. List Recent Versions

```bash
git log --oneline -n 10
git tag --sort=-creatordate | head -n 10
```

**Output:**
```
v1.3.0 (current) ❌ FAILING - Health: 502
v1.2.5 (previous) ✅ STABLE - Health: 200 OK, Uptime: 99.8%
v1.2.4 ✅ STABLE
v1.2.3 ✅ STABLE
```

**Metadata tracking:**
- Commit SHA
- Deploy timestamp
- Health status (last known)
- Uptime percentage (if tracked)
- Issue description (se falhou)

### 2. Select Target Version

**Strategies:**

#### A. Interactive (default)
```
➜ Rollback to: [2] v1.2.5 (recommended)

Available versions:
1. v1.3.0 (current) ❌ FAILING
2. v1.2.5 (previous) ✅ STABLE (recommended)
3. v1.2.4 ✅ STABLE
4. v1.2.3 ✅ STABLE

Enter number [2]:
```

#### B. Automatic (--auto)
```
Last known good: v1.2.5 (health OK, deployed 2h ago)
Auto-selecting v1.2.5...
```

#### C. Specific (--to-version)
```
Target version specified: v1.2.5
Validating...
```

### 3. Confirm Rollback (se não --auto)

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 ROLLBACK PLAN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Current: v1.3.0 (a3f5c21) - Port mismatch issue
Target:  v1.2.5 (7d3a1f2) - Stable, 99.8% uptime

Changes (diff):
  - src/server.ts: PORT 8080 → 3000
  - docker-compose.yml: Traefik port fix
  + Reverts 3 commits

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Confirm rollback? [Y/n]:
```

### 4. Perform Rollback

**Method A: Git Revert (small rollback, 1-3 commits)**
```bash
git revert --no-commit a3f5c21..HEAD
git commit -m "revert: rollback to v1.2.5 due to port mismatch"
```

**Method B: Git Checkout (large rollback, >3 commits)**
```bash
git checkout 7d3a1f2
git checkout -b rollback-to-v1.2.5
git push origin rollback-to-v1.2.5:main --force
```

### 5. Push & Redeploy

```bash
git push origin main
```

**Via API (preferido - sincroniza com GUI):**
```bash
# Obter token
TOKEN=$(cat /etc/easypanel/.api-token)

# Trigger redeploy via API
curl -s -X POST "http://localhost:3000/api/trpc/services.app.redeployService" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"projectName":"PROJECT","serviceName":"SERVICE"}}'
```

**Se CI/CD configurado:**
- Trigger automático via webhook
- Aguardar build (timeout 5min)

### 6. Monitor Rollback

```bash
# Poll EasyPanel deploy
docker service ps <service>
docker service logs <service> --tail 50 --follow
```

**Timeline:**
```
[00:00] ✅ Git revert completed
[00:05] ✅ Push to Gitea
[01:45] ✅ EasyPanel build started
[03:20] ✅ Container started
[03:28] ✅ Health check: 200 OK
```

### 7. Validate Rollback

#### Health Check (5 retries)
```bash
curl -f https://domain/health
```

**Expected:** 200 OK

#### Logs Check
```bash
docker logs <container> --tail 100 | grep -i error
```

**Expected:** No critical errors

#### Metrics Check
```bash
docker stats <container> --no-stream
```

**Expected:**
- CPU < 80%
- RAM < 80%
- No OOM kills

### 8. Success Report

```
✅ ROLLBACK COMPLETE

Total time: 3m 30s
Service restored: https://domain.descomplicar.pt
Health: ✅ 200 OK
Version: v1.2.5 (7d3a1f2)

🛠️  NEXT STEPS
1. Investigate root cause: /easypanel-troubleshoot
2. Fix issues locally
3. Test fix: docker build + docker run
4. Redeploy: /easypanel-deploy
```

## Output Format (Success)

```
🔄 EasyPanel Rollback: dashboard-api

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📜 AVAILABLE VERSIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. v1.3.0 (current) ❌ FAILING
   - Commit: a3f5c21
   - Deployed: 15min ago
   - Health: 502 Bad Gateway
   - Issue: Port mismatch

2. v1.2.5 (previous) ✅ STABLE
   - Commit: 7d3a1f2
   - Deployed: 2h ago
   - Health: 200 OK (before upgrade)
   - Uptime: 99.8% (last 7 days)

3. v1.2.4 ✅ STABLE
   - Commit: 9c4b3a1
   - Deployed: 1 day ago

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

➜ Rollback to: v1.2.5 (recommended)

Confirm? [Y/n]: y

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️  ROLLBACK IN PROGRESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[00:00] ✅ Git revert (a3f5c21 → 7d3a1f2)
[00:05] ✅ Commit rollback
[00:10] ✅ Push to Gitea
[01:45] ✅ EasyPanel redeploy started
[03:20] ✅ Container started
[03:28] ✅ Health check: 200 OK
[03:30] ✅ Metrics validated (CPU: 11%, RAM: 42MB)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ ROLLBACK COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Total time: 3m 30s
Service restored: https://dashboard.descomplicar.pt
Health: ✅ 200 OK

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛠️  NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Investigate root cause of v1.3.0 failure
   → /easypanel-troubleshoot dashboard-api

2. Fix issues locally
   → Update Dockerfile EXPOSE port

3. Test fix locally
   → docker build + docker run + test

4. Redeploy
   → /easypanel-deploy

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 ROLLBACK LOGGED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Desk CRM Task #1502: Comment added
Gitea: Rollback commit pushed (4e8a9c3)
```

## Output Format (Failed)

```
❌ ROLLBACK FAILED

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⏱️  TIMELINE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[00:00] ✅ Git revert
[00:05] ✅ Push to Gitea
[01:45] ✅ Build started
[03:20] ✅ Container started
[03:28] ❌ Health check: 500 Internal Server Error

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 ERROR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Target version v1.2.5 also failing after rollback
Possible causes:
- Database schema incompatibility
- Environment variable missing
- External dependency changed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚨 MANUAL INTERVENTION REQUIRED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Check logs: /easypanel-troubleshoot dashboard-api
2. Verify database migrations
3. Check environment variables
4. Consider rollback to v1.2.4 (older stable)
```

## Flags

### --auto

Selecção automática da "last known good version":
- Versão anterior com health OK
- Sem confirmação interactiva
- Deploy imediato

**Uso em automation:**
```bash
# Triggered by monitoring alert
if [[ $(curl -s -o /dev/null -w "%{http_code}" https://domain/health) != "200" ]]; then
  /easypanel-rollback dashboard-api --auto
fi
```

### --to-version

Especificar versão alvo exacta:
```bash
/easypanel-rollback dashboard-api --to-version v1.2.3
```

**Validações:**
- Versão existe? (git tag)
- Versão não é actual
- Versão é anterior (não futura)

## Version Metadata Tracking

**Stored in:** `.easypanel/deploy-history.json`

```json
{
  "versions": [
    {
      "tag": "v1.2.5",
      "commit": "7d3a1f2",
      "timestamp": "2026-02-04T10:30:00Z",
      "health_status": "ok",
      "health_checks": 1523,
      "health_failures": 3,
      "uptime_percentage": 99.8,
      "deploy_duration_ms": 180000,
      "image_size_mb": 82,
      "rollback_safe": true
    }
  ]
}
```

## Integration com /easypanel-deploy

Quando `/easypanel-deploy` detecta falha, chama automaticamente:
```bash
/easypanel-rollback --auto
```

## API Endpoints Usados

Ver skill `/easypanel-api` para documentação completa.

| Acção | Endpoint |
|-------|----------|
| Inspeccionar serviço | `GET services.app.inspectService` |
| Redeploy | `POST services.app.redeployService` |
| Obter logs | `GET services.app.getServiceLogs` |
| Estado serviço | `GET services.app.inspectService` |

## MCPs Necessários

- ✅ `gitea` - Git operations e tags
- ✅ `ssh-unified` - Acesso ao servidor para API
- ✅ `desk-crm-v3` - Log rollback em comentário tarefa

## Tools Necessários

```bash
# Git
git log
git tag
git revert
git checkout
git push --force (com cuidado!)

# Docker
docker service ps
docker logs

# Curl
curl -f https://domain/health
```

## Safety Checks

1. **Backup actual state** antes de rollback
2. **Validate target version** existe
3. **Check database migrations** compatibility
4. **Confirm with user** (excepto --auto)
5. **Monitor rollback** até health OK

## Checklist Execução

- [ ] List recent versions (git log + tags)
- [ ] Fetch deploy history metadata
- [ ] Select target version (interactive/auto/specific)
- [ ] Show rollback plan + diff
- [ ] Confirm with user (se não --auto)
- [ ] Backup actual state
- [ ] Perform git revert ou checkout
- [ ] Commit rollback
- [ ] Push to Gitea
- [ ] Monitor redeploy (5min timeout)
- [ ] Health check (5 retries)
- [ ] Validate logs (no errors)
- [ ] Validate metrics (CPU, RAM)
- [ ] Report success ou fail
- [ ] Log rollback em Desk CRM

---

**Versão:** 1.0.0 | **Autor:** Descomplicar® | **Data:** 2026-02-04

## Metadata (Desk CRM Task #65)

```
Tarefa: SKL: /easypanel-rollback - Automated Rollback
Milestone: 294 (Skills Claude Code)
Tags: skill(79), stackworkflow(75), claude-code(81), activo(116)
Responsáveis: Emanuel(1), AikTop(25)
Status: 4 (Em progresso) → 5 (Concluído)
```

---

**/** @author Descomplicar® | @link descomplicar.pt | @copyright 2026 **/

---


## Quando NÃO Usar

- Para tarefas fora do domínio de especialização desta skill
- Quando outra skill mais específica está disponível
- Para operações que requerem confirmação manual do utilizador