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

name, description, layer

name	description	layer
easypanel-cicd	Configuracao de CI/CD com Gitea Actions para auto-deploy no EasyPanel via webhook — setup de workflows, secrets e validacao.	wiki

/easypanel-cicd - CI/CD Gitea Actions para EasyPanel

Configuracao completa de pipelines CI/CD que ligam repositorios Gitea ao EasyPanel para auto-deploy.

---

Quando usar

• Configurar auto-deploy de um repositorio Gitea para EasyPanel
• Criar workflow Gitea Actions com testes + deploy
• Obter e configurar webhook URL de um servico
• Diagnosticar pipelines CI/CD falhados
• Adicionar CI/CD a projectos existentes no EasyPanel

Quando nao usar

• Para deploy manual (usar /easypanel-deploy)
• Para scaffold de projecto novo (usar /easypanel-init)
• Para troubleshooting de containers (usar /easypanel-troubleshoot)

---

Sintaxe

/easypanel-cicd <repo-name>                    # Setup completo (workflow + secrets + webhook)
/easypanel-cicd <repo-name> --webhook-only      # Apenas obter/configurar webhook
/easypanel-cicd <repo-name> --diagnose          # Diagnosticar pipeline falhado

---

Arquitectura

Gitea (push main) --> Gitea Actions Runner --> Testes + Build --> Webhook POST --> EasyPanel Redeploy
                      (3 runners activos)                        (deploy URL)     (build + container)

Componentes:

• Gitea Actions Runners: 3 replicas activas (descomplicar_gitea-runner)
• Webhook URL: Cada servico EasyPanel tem deploymentUrl unico
• Formato: http://<IP>:3000/api/deploy/<service-token>

---

Workflow completo

1. Obter webhook URL do servico

TOKEN=$(cat /etc/easypanel/.api-token)

# Via inspectService — campo deploymentUrl
INPUT='{"json":{"projectName":"descomplicar","serviceName":"SERVICE_NAME"}}'
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$INPUT'))")
curl -s "http://localhost:3000/api/trpc/services.app.inspectService?input=$ENCODED" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['result']['data']['json']['deploymentUrl'])"

Formato da URL: http://178.63.18.51:3000/api/deploy/<service-token>

Nota: O token e unico por servico e nao expira. Nao confundir com o API token geral.

2. Configurar secret no repositorio Gitea

Via MCP Gitea:

mcp__gitea__upsert_repo_action_secret({
  owner: "ealmeida",
  repo: "REPO_NAME",
  secretname: "EASYPANEL_DEPLOY_URL",
  body: { data: "http://178.63.18.51:3000/api/deploy/<service-token>" }
})

Secrets adicionais recomendados:

• EASYPANEL_DEPLOY_URL — webhook URL (obrigatorio)
• DEPLOY_DOMAIN — dominio do servico (opcional, para health check)

3. Criar workflow Gitea Actions

Criar .gitea/workflows/deploy.yml no repositorio:

Template basico (apenas deploy)

name: Deploy to EasyPanel

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger EasyPanel Deploy
        run: |
          RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}")
          if [ "$RESPONSE" != "200" ]; then
            echo "Deploy trigger failed with HTTP $RESPONSE"
            exit 1
          fi
          echo "Deploy triggered successfully"

Template completo (testes + build + deploy + health check)

name: CI/CD Pipeline

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint --if-present

      - name: Test
        run: npm test --if-present

      - name: Build
        run: npm run build

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    steps:
      - name: Trigger EasyPanel Deploy
        run: |
          echo "Triggering deploy..."
          RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" -X POST "${{ secrets.EASYPANEL_DEPLOY_URL }}")
          if [ "$RESPONSE" != "200" ]; then
            echo "Deploy trigger failed with HTTP $RESPONSE"
            exit 1
          fi
          echo "Deploy triggered (HTTP $RESPONSE)"

      - name: Wait for deployment
        run: sleep 120

      - name: Health check
        if: ${{ secrets.DEPLOY_DOMAIN != '' }}
        run: |
          for i in 1 2 3 4 5; do
            STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://${{ secrets.DEPLOY_DOMAIN }}/health" || echo "000")
            echo "Health check $i/5: HTTP $STATUS"
            if [ "$STATUS" = "200" ]; then
              echo "Service healthy"
              exit 0
            fi
            sleep 15
          done
          echo "Health check failed after 5 attempts"
          e