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

name, description, author, version, quality_score, user_invocable, desk_task, allowed-tools, dependencies

name	description	author	version	quality_score	user_invocable	desk_task	allowed-tools	dependencies
easypanel-rollback	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".	Descomplicar® Crescimento Digital	2.0.0	70	true	TBD	Task	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

/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