@saulwade/swl-ses 1.0.0

package/habilidades/ci-cd-pipelines/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: ci-cd-pipelines
+description: CI/CD con GitHub Actions y GitLab CI. Stages de lint, test, build, deploy. Caching, artifacts, matrix builds, secrets management, deployment strategies, monorepos y quality gates.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para Kubernetes Deployments o Helm releases — para Kubernetes cargar `kubernetes-orquestacion`."
+  - "No cargar para Terraform o infraestructura como código — para IaC cargar `terraform-experto`."
+  - "No cargar para SRE, SLOs, runbooks o post-mortems — para operaciones en producción cargar `sre-patrones`."
+  - "No cargar para Git workflow (branching, commits, PRs) — para workflow de git cargar la regla `git-workflow.md`."
+evolvable: true  # default para skill estandar
+---
+# CI/CD Pipelines — Integración y Entrega Continua
+
+## Cuándo NO cargar
+
+- La tarea es Kubernetes: manifiestos de Deployment, Helm releases, kubectl — cargar `kubernetes-orquestacion`.
+- El trabajo es infraestructura como código con Terraform — cargar `terraform-experto`.
+- El tema es SRE: SLOs, runbooks, alertas, post-mortems — cargar `sre-patrones`.
+- La tarea es Git workflow: branching strategy, mensajes de commit, revisión de PRs — cargar la regla `git-workflow.md`.
+
+Un pipeline bien diseñado detecta errores antes de producción, entrega valor continuamente
+y construye confianza en el equipo. Este skill cubre patrones para Python, Node y containers.
+
+---
+
+## Reglas Obligatorias
+
+1. **Lint como primer gate** — no ejecutar tests si el código no formatea.
+2. **Cobertura mínima como quality gate** — `--cov-fail-under=80`.
+3. **Security scanning** — código, dependencias e imagen Docker.
+4. **NUNCA credenciales hardcodeadas** en YAML — usar GitHub Secrets / GitLab CI Variables.
+5. **`concurrency: cancel-in-progress: true`** — evitar deploys simultáneos.
+6. **Imagen Docker con tag de versión exacta** — NUNCA `:latest` en producción.
+7. **Smoke tests post-deploy** — verificar health endpoint después de cada deploy.
+8. **Staging antes de producción** — sin excepción.
+
+---
+
+## Estructura de Pipeline (GitHub Actions)
+
+```yaml
+# Orden de jobs con dependencias
+jobs:
+  lint:        # Primero: formato y types
+  test:        # Segundo: requiere lint
+    needs: lint
+  security:    # Paralelo a test: requiere lint
+    needs: lint
+  build:       # Tercero: requiere test + security
+    needs: [test, security]
+  deploy-staging:
+    needs: build
+    if: github.ref == 'refs/heads/develop'
+  deploy-production:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+```
+
+Patrón clave: `concurrency` para cancelar runs previos del mismo PR:
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+---
+
+## Quality Gates — No Negociables
+
+```bash
+# 1. Cobertura mínima
+pytest --cov-fail-under=80
+
+# 2. Sin vulnerabilidades críticas
+trivy image --exit-code 1 --severity CRITICAL mi-imagen:latest
+
+# 3. Lint sin errores
+ruff check . --exit-non-zero-on-fix
+
+# 4. Type checking
+mypy app/ --strict
+
+# 5. No secrets en código
+trufflehog filesystem --fail ./
+```
+
+---
+
+## Caching — Reducir Tiempo de Pipeline
+
+```yaml
+# Cache automático de pip
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.12"
+    cache: pip
+
+# Docker layer cache
+- uses: docker/build-push-action@v5
+  with:
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+---
+
+## Secrets — Gestión Correcta
+
+- SIEMPRE usar secrets del CI, NUNCA en código ni archivos de pipeline.
+- Environment-scoped secrets: staging y prod tienen valores distintos.
+- Rotar secrets periódicamente via CLI: `gh secret set API_KEY --env production`.
+
+---
+
+## Anti-patrones de CI/CD
+
+| Anti-patrón | Corrección |
+|-------------|------------|
+| Tests que dependen de orden | Tests independientes con fixtures |
+| Credenciales en YAML | GitHub Secrets + env vars |
+| Pipeline sin caché | `cache:` en dependencias |
+| Deploy sin smoke tests | Health check post-deploy |
+| Un solo job gigante | Jobs separados con `needs:` |
+| Sin `concurrency:` | `cancel-in-progress: true` |
+| `:latest` en producción | SHA o semver en imagen |
+
+---
+
+## Checklist de Pipeline Productivo
+
+- [ ] Lint y format check como primer gate
+- [ ] Tests con BD real (no solo mocks)
+- [ ] Cobertura mínima como quality gate
+- [ ] Security scanning (código + deps + imagen)
+- [ ] Docker build con cache habilitado
+- [ ] Deploy a staging antes de producción
+- [ ] Smoke tests post-deploy
+- [ ] Notificaciones de fallo en canal de alertas
+- [ ] Secrets en el sistema de CI (no en código)
+- [ ] `concurrency` configurado
+- [ ] Tiempo total < 15 minutos
+
+Para pipelines completos de GitHub Actions y GitLab CI, matrix builds, monorepo y notificaciones, ver [recursos/pipelines-completos.md](recursos/pipelines-completos.md).
+
+Para template de GitHub Actions reutilizable, ver [recursos/github-actions-template.yaml](recursos/github-actions-template.yaml).
+
+## Gotchas / Errores comunes no obvios
+
+**`actions/cache` no hace hit si el lock file cambia en la misma PR que agrega la dependencia**: la clave del cache incluye el hash del `package-lock.json` o `requirements.txt` — cuando el PR agrega una nueva dependencia, la clave cambia y el cache no existe aún, causando una instalación completa. Causa: es el comportamiento correcto y esperado, pero sorprende en PRs de "solo agrego una dependencia". Fix: aceptar que el primer build de una nueva dependencia siempre es lento — el cache se llenará en builds subsiguientes. Optimizar usando `restore-keys` para hit parcial.
+
+**`concurrency: cancel-in-progress: true` cancela el deploy de staging cuando se pushea al PR antes de que el deploy termine**: si alguien hace dos pushes rápidos al mismo PR, el primer deploy de staging se cancela a la mitad. Causa: `cancel-in-progress` cancela cualquier run del mismo grupo de concurrencia, incluyendo deploys en progreso. Fix: para jobs de deploy, usar una concurrencia diferente: `group: deploy-staging-${{ github.ref }}` para agrupar solo deploys del mismo branch, y considerar `cancel-in-progress: false` para deploys que no deben cancelarse a la mitad.
+
+**Secrets definidos en GitHub Actions no están disponibles en workflows de forks en PRs externas**: los workflows disparados por un PR de un fork (contribuidor externo) no tienen acceso a los secrets del repositorio por seguridad. Causa: prevención de exfiltración de secrets a forks maliciosos. Fix: usar el evento `pull_request_target` con cuidado para acceder a secrets en PRs de forks, pero solo para jobs que no ejecutan código del PR — los jobs de lint/test pueden correr sin secrets; los de deploy sí necesitan el evento `push` al branch base.
+
+**`docker/build-push-action` con `cache-from: type=gha` puede hacer el build más lento si el cache es muy grande**: el cache de GitHub Actions (10GB límite) se llena con layers de Docker — si se usan imágenes base grandes y muchos stages, el cache puede alcanzar el límite y las layers más antiguas se evictan, causando rebuilds completos. Causa: el cache de GHA tiene límite de 10GB por repositorio. Fix: usar `cache-from: type=registry,ref=ghcr.io/org/app:cache` con un registro de contenedores para cache ilimitado, o usar `mode=min` en el cache para solo guardar las layers finales en lugar de todas las intermedias.

package/habilidades/ci-cd-pipelines/recursos/github-actions-template.yaml

@@ -0,0 +1,403 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Template de GitHub Actions CI/CD
+# Cubre: lint, type-check, tests, build de Docker, deploy a staging y producción.
+#
+# INSTRUCCIONES DE USO:
+#   1. Copiar a .github/workflows/ci-cd.yml
+#   2. Reemplazar todos los valores entre [corchetes] con los reales
+#   3. Configurar los secrets en Settings → Secrets and variables → Actions
+#   4. Ajustar los jobs según el stack del proyecto (ver comentarios INSTRUCCIÓN)
+#
+# SECRETS REQUERIDOS (configurar en el repo antes de hacer push):
+#   REGISTRY_USERNAME         Usuario del container registry
+#   REGISTRY_PASSWORD         Token del container registry
+#   STAGING_DEPLOY_KEY        SSH key o token para deploy a staging
+#   PRODUCTION_DEPLOY_KEY     SSH key o token para deploy a producción
+#   SLACK_WEBHOOK_URL         (opcional) para notificaciones de deploy
+# ═══════════════════════════════════════════════════════════════════════════════
+
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+    tags:
+      - "v*.*.*"
+  pull_request:
+    branches:
+      - main
+      - develop
+
+# Cancelar runs previos del mismo PR o branch (ahorra minutos de CI)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# ─── Variables globales ────────────────────────────────────────────────────────
+env:
+  PYTHON_VERSION: "3.12"
+  NODE_VERSION: "20"
+  # INSTRUCCIÓN: reemplazar con el registry real (ghcr.io, docker.io, etc.)
+  REGISTRY: "ghcr.io"
+  IMAGE_NAME: "${{ github.repository }}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+jobs:
+
+  # ─── Job 1: Lint y type-check ────────────────────────────────────────────────
+  lint:
+    name: "Lint y Type Check"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Setup Python ${{ env.PYTHON_VERSION }}"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: "Instalar herramientas de lint"
+        run: pip install ruff mypy types-requests
+
+      # INSTRUCCIÓN: ajustar según las herramientas que uses
+      - name: "Ruff — linter y formatter"
+        run: |
+          ruff check . --output-format=github
+          ruff format . --check
+
+      - name: "Mypy — type checking"
+        run: mypy . --ignore-missing-imports
+
+      # INSTRUCCIÓN: si hay frontend Angular/Node, agregar este bloque
+      # - name: "Setup Node ${{ env.NODE_VERSION }}"
+      #   uses: actions/setup-node@v4
+      #   with:
+      #     node-version: ${{ env.NODE_VERSION }}
+      #     cache: npm
+      # - name: "npm install"
+      #   run: npm ci
+      # - name: "ESLint"
+      #   run: npm run lint
+
+  # ─── Job 2: Tests ────────────────────────────────────────────────────────────
+  test:
+    name: "Tests"
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: [lint]
+
+    # INSTRUCCIÓN: ajustar los servicios según el stack del proyecto
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: test_user
+          POSTGRES_PASSWORD: test_password
+          POSTGRES_DB: test_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+      # INSTRUCCIÓN: descomentar si usas Redis
+      # redis:
+      #   image: redis:7-alpine
+      #   options: >-
+      #     --health-cmd "redis-cli ping"
+      #     --health-interval 10s
+      #     --health-timeout 5s
+      #     --health-retries 5
+      #   ports:
+      #     - 6379:6379
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Setup Python ${{ env.PYTHON_VERSION }}"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+          cache: pip
+
+      - name: "Instalar dependencias"
+        run: pip install -r requirements.txt -r requirements-test.txt
+
+      - name: "Aplicar migraciones de base de datos"
+        env:
+          DATABASE_URL: "postgresql://test_user:test_password@localhost:5432/test_db"
+        run: |
+          # INSTRUCCIÓN: ajustar al sistema de migraciones del proyecto
+          alembic upgrade head
+
+      - name: "Ejecutar tests con cobertura"
+        env:
+          DATABASE_URL: "postgresql://test_user:test_password@localhost:5432/test_db"
+          # INSTRUCCIÓN: agregar más variables de entorno que necesiten los tests
+          APP_ENV: "test"
+          SECRET_KEY: "test-secret-key-no-usar-en-produccion"
+        run: |
+          pytest \
+            --cov=[nombre-del-modulo] \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            --cov-fail-under=80 \
+            -v \
+            --tb=short
+
+      - name: "Subir reporte de cobertura"
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report
+          path: coverage.xml
+          retention-days: 7
+
+      # INSTRUCCIÓN: descomentar para integración con Codecov
+      # - name: "Subir cobertura a Codecov"
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     file: ./coverage.xml
+      #     fail_ci_if_error: true
+
+  # ─── Job 3: Build de imagen Docker ───────────────────────────────────────────
+  build:
+    name: "Build Docker Image"
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: [test]
+    # Solo construir en push a branches principales o en tags de release
+    if: github.event_name == 'push'
+
+    outputs:
+      image-tag: ${{ steps.meta.outputs.tags }}
+      image-digest: ${{ steps.build.outputs.digest }}
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Configurar Docker Buildx"
+        uses: docker/setup-buildx-action@v3
+
+      - name: "Login al container registry"
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.REGISTRY_USERNAME }}
+          password: ${{ secrets.REGISTRY_PASSWORD }}
+
+      - name: "Extraer metadata para el tag"
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=sha-,format=short
+          labels: |
+            org.opencontainers.image.title=[Nombre de la aplicación]
+            org.opencontainers.image.description=[Descripción corta]
+
+      - name: "Build y Push"
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # Cache: reutilizar capas de builds anteriores
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          # Build args si el Dockerfile los necesita
+          build-args: |
+            PYTHON_VERSION=${{ env.PYTHON_VERSION }}
+
+      - name: "Escanear imagen por vulnerabilidades"
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.meta.outputs.version }}"
+          format: "sarif"
+          output: "trivy-results.sarif"
+          exit-code: "1"
+          severity: "CRITICAL,HIGH"
+
+      - name: "Subir resultados de Trivy a GitHub Security"
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: "trivy-results.sarif"
+
+  # ─── Job 4: Deploy a Staging ─────────────────────────────────────────────────
+  deploy-staging:
+    name: "Deploy → Staging"
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: [build]
+    # Solo desplegar en el branch develop
+    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
+    environment:
+      name: staging
+      url: "https://[tu-app-staging.com]"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      # INSTRUCCIÓN: ajustar según la estrategia de deploy del proyecto
+      # Opción A: Deploy via SSH
+      - name: "Deploy via SSH a staging"
+        uses: appleboy/ssh-action@v1
+        with:
+          host: "[staging-server.com]"
+          username: "deploy"
+          key: ${{ secrets.STAGING_DEPLOY_KEY }}
+          script: |
+            cd /opt/[nombre-app]
+            docker compose pull
+            docker compose up -d --no-deps --force-recreate [nombre-servicio]
+            docker compose exec -T [nombre-servicio] alembic upgrade head
+            docker system prune -f
+
+      # INSTRUCCIÓN: Opción B: Deploy via kubectl (Kubernetes)
+      # - name: "Setup kubectl"
+      #   uses: azure/setup-kubectl@v4
+      # - name: "Deploy a Kubernetes staging"
+      #   run: |
+      #     kubectl set image deployment/[nombre-app] \
+      #       [nombre-app]=${{ needs.build.outputs.image-tag }} \
+      #       -n staging
+
+      - name: "Verificar health check"
+        run: |
+          sleep 15
+          curl -f https://[tu-app-staging.com]/health || exit 1
+
+      - name: "Notificar deploy exitoso"
+        if: success()
+        run: |
+          curl -s -X POST "${{ secrets.SLACK_WEBHOOK_URL }}" \
+            -H "Content-Type: application/json" \
+            -d "{\"text\": \"Deploy a staging exitoso: ${{ github.sha }} — <https://[tu-app-staging.com]|Ver staging>\"}"
+
+  # ─── Job 5: Deploy a Producción ──────────────────────────────────────────────
+  deploy-production:
+    name: "Deploy → Producción"
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: [build]
+    # Solo desplegar en tags de release (v*.*.*)
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: production
+      url: "https://[tu-app-produccion.com]"
+      # Requiere aprobación manual en GitHub Environments antes de ejecutar
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Validar que el tag coincide con el changelog"
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          if ! grep -q "## \[${VERSION}\]" CHANGELOG.md 2>/dev/null; then
+            echo "ERROR: CHANGELOG.md no tiene entrada para la versión ${VERSION}"
+            echo "Ejecuta: bash habilidades/release-semver/scripts/generar-changelog.sh"
+            exit 1
+          fi
+
+      # INSTRUCCIÓN: misma estrategia que staging pero apuntando a producción
+      - name: "Deploy via SSH a producción"
+        uses: appleboy/ssh-action@v1
+        with:
+          host: "[prod-server.com]"
+          username: "deploy"
+          key: ${{ secrets.PRODUCTION_DEPLOY_KEY }}
+          script: |
+            set -e
+            cd /opt/[nombre-app]
+
+            # Backup de la base de datos antes del deploy
+            docker compose exec -T postgres pg_dump -U [db_user] [db_name] \
+              > /backups/pre-deploy-$(date +%Y%m%d-%H%M%S).sql
+
+            # Deploy con zero-downtime (rolling update)
+            docker compose pull
+            docker compose up -d --no-deps --force-recreate [nombre-servicio]
+
+            # Migraciones
+            docker compose exec -T [nombre-servicio] alembic upgrade head
+
+            # Limpiar imágenes antiguas
+            docker system prune -f --filter "until=24h"
+
+      - name: "Verificar health check de producción"
+        run: |
+          sleep 20
+          for i in {1..5}; do
+            curl -f https://[tu-app-produccion.com]/health && break
+            echo "Intento $i fallido, esperando 10s..."
+            sleep 10
+          done
+
+      - name: "Crear GitHub Release"
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: false
+          body_path: CHANGELOG.md
+          # INSTRUCCIÓN: agregar artefactos del release si corresponde
+          # files: |
+          #   dist/*.whl
+          #   dist/*.tar.gz
+
+      - name: "Notificar release a producción"
+        if: success()
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/v}"
+          curl -s -X POST "${{ secrets.SLACK_WEBHOOK_URL }}" \
+            -H "Content-Type: application/json" \
+            -d "{\"text\": \"Release v${VERSION} desplegado a producción exitosamente\"}"
+
+      - name: "Rollback automático si el health check falla"
+        if: failure()
+        uses: appleboy/ssh-action@v1
+        with:
+          host: "[prod-server.com]"
+          username: "deploy"
+          key: ${{ secrets.PRODUCTION_DEPLOY_KEY }}
+          script: |
+            cd /opt/[nombre-app]
+            # Revertir a la imagen anterior
+            docker compose up -d --no-deps --force-recreate [nombre-servicio]
+            echo "ROLLBACK ejecutado — revisar logs manualmente"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# CONFIGURACIÓN ADICIONAL RECOMENDADA:
+#
+# 1. Branch protection rules (Settings → Branches → Add rule para 'main'):
+#    - Require status checks: lint, test
+#    - Require pull request reviews before merging
+#    - Require signed commits
+#    - Do not allow bypassing
+#
+# 2. Environments (Settings → Environments):
+#    - staging: sin restricciones de revisores
+#    - production: required reviewers = [tu usuario]
+#
+# 3. Secrets necesarios (Settings → Secrets → Actions):
+#    REGISTRY_USERNAME, REGISTRY_PASSWORD
+#    STAGING_DEPLOY_KEY, PRODUCTION_DEPLOY_KEY
+#    SLACK_WEBHOOK_URL (opcional)
+# ═══════════════════════════════════════════════════════════════════════════════