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

name, description, disable-model-invocation

name	description	disable-model-invocation
easypanel-rollback	Rollback seguro de deployments EasyPanel para versões anteriores estáveis via API oficial.	true

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

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

Exemplos

# 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

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)

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)

git checkout 7d3a1f2
git checkout -b rollback-to-v1.2.5
git push origin rollback-to-v1.2.5:main --force

5. Push & Redeploy

git push origin main

Via API (preferido - sincroniza com GUI):

# 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

# 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)

curl -f https://domain/health

Expected: 200 OK

Logs Check

docker logs <container> --tail 100 | grep -i error

Expected: No critical errors

Metrics Check

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:

# 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:

/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

{
  "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:

/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

# 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