⚙️ 3.9 · CI/CD con GitHub Actions: testing, build y deploy automatizado en cada commit

🎯 Objetivo del tema

🗺️ Mapa del tema

Imagina esto: haces push, esperas 2 minutos, abres tu app, y algo está roto. ¿Qué pasó? Alguien metió un bug. Pero tú no te enteraste hasta producción. Con CI/CD, ese escenario NO EXISTE: cada push dispara tests automáticos. Si algo se rompe, GitHub te avisa ANTES de hacer merge a main. Y cuando haces merge, el deploy es automático. Es la diferencia entre 'rezar para que no se rompa' y 'tener un seguro automático'. En este tema configuras un pipeline completo para tu Atlas Mundial.

3.9.1 Qué es CI/CD y por qué tu app lo necesita

CI significa Continuous Integration (Integración Continua): cada vez que alguien hace push, se ejecutan los tests automáticamente. CD significa Continuous Deployment (Despliegue Continuo): si los tests pasan, el código se deploya a producción automáticamente. Es el flujo que usan Netflix, Google, Facebook, y todas las empresas de software modernas. Sin CI/CD, tu equipo acumula código sin probar durante semanas y el día del release es un desastre. Con CI/CD, cada cambio se prueba y deploya de forma aislada, reduciendo el riesgo 100x.

El antes y el después de CI/CD

• ANTES de CI/CD: devs programan 2 semanas → merge conflictivo → deploy manual → algo se rompe → pánico a las 3am → hotfix urgente → bug nuevo.
• DESPUÉS de CI/CD: dev hace push → tests automáticos en 3 min → si pasan, deploy a staging en 1 min → QA prueba → merge a main → deploy a producción en 2 min. Sin humanos involucrados en el deploy.
• El secreto: cada commit es PEQUEÑO y se prueba AISLADAMENTE. Si falla, solo revientas ESE commit, no toda la release.
• Las métricas mejoran: 95% menos bugs en producción, 10x más frecuencia de deploys, 50% menos tiempo de recuperación ante incidentes.

3.9.2 GitHub Actions: workflows en YAML

GitHub Actions es la herramienta de CI/CD INTEGRADA en GitHub. Es gratis para repos públicos (2000 min/mes) y tiene plan gratis para privados (con límites). Se configura con un archivo .github/workflows/ci.yml donde defines en YAML los eventos que disparan el workflow, los jobs, los steps, y las actions a usar. Es la opción #1 para aprender porque no necesitas otra cuenta, otra herramienta, ni otro login: ya estás en GitHub.

Anatomía básica de un workflow

# .github/workflows/ci.yml: el nombre del archivo puede ser cualquiera
# Convención: ci.yml, test.yml, deploy.yml, etc.

name: CI Pipeline    # nombre que aparece en la pestaña Actions de GitHub

# TRIGGERS: en QUÉ eventos se ejecuta este workflow
on:
  push:
    branches: [main, develop]   # cuando hay push a main o develop
  pull_request:
    branches: [main]            # cuando se abre/actualiza un PR a main
  # Otros triggers comunes:
  # schedule:                    # tareas programadas (cron)
  #   - cron: '0 2 * * *'        # todos los días a las 2am
  # workflow_dispatch:            # botón 'Run workflow' manual

# JOBS: grupos de steps que se ejecutan (pueden ser en paralelo)
jobs:
  # job 1: correr tests
  test:
    runs-on: ubuntu-latest     # sistema operativo del runner (ubuntu/windows/macos)
    # Opciones de runs-on: ubuntu-latest, windows-latest, macos-latest
    # También: ubuntu-22.04, self-hosted (tu propio runner)

    steps:
      # step 1: clonar el repo (casi siempre es el primero)
      - name: Checkout code
        uses: actions/checkout@v4   # 'uses' = usar una action de la marketplace

      # step 2: instalar Node.js 20
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'              # cache de dependencias para acelerar

      # step 3: instalar dependencias
      - name: Install dependencies
        run: npm ci                  # 'run' = ejecutar un comando shell
        # npm ci vs npm install: npm ci es más rápido y estricto (usa package-lock.json)

      # step 4: correr tests con coverage
      - name: Run tests
        run: npm run test:coverage

      # step 5: subir reporte de coverage a Codecov (opcional)
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          token: ${{ secrets.CODECOV_TOKEN }}   # secret (lo configuras en Settings > Secrets)
        if: always()    # 'if: always()' ejecuta este step incluso si los tests fallan

Workflow básico: test en cada PR a main

El job de build: validar que el bundle de producción compila

# Añadir este job al mismo workflow
  build:
    runs-on: ubuntu-latest
    needs: test                  # 'needs' = depende del job 'test' (se ejecuta DESPUÉS)

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Build production bundle
        run: npm run build
        env:
          # Variables de entorno para el build (NO son secrets, son públicas)
          VITE_API_URL: https://api.miapp.com
          VITE_SUPABASE_URL: https://xxx.supabase.co

      # Subir el artefacto de build (opcional, útil para debuggear)
      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7         # cuánto tiempo se guarda (max 90 días)

Job de build con Node 20 y caché de npm

3.9.3 Triggers, jobs y steps: la anatomía de un workflow

Un workflow de GitHub Actions tiene 3 niveles: TRIGGERS (cuándo se ejecuta), JOBS (qué se ejecuta en paralelo), y STEPS (cómo se ejecuta cada job). Los jobs pueden depender entre sí (needs), pueden correr en paralelo, en diferentes OS, y pueden tener una matriz de versiones. Es como Lego: combinas estos elementos para construir tu pipeline perfecto.

Triggers: los 10 más usados

• on: push → cuando se hace push a cualquier branch.
• on: push.branches: [main] → solo a main (ahorra minutos de CI).
• on: pull_request → cuando se abre/actualiza un PR.
• on: pull_request.target: main → PRs que apuntan a main.
• on: workflow_dispatch → botón 'Run workflow' manual desde la UI.
• on: schedule → tareas programadas con cron (ej: nightly builds).
• on: release → cuando se publica un release.
• on: issues → cuando se abre/cierra/etiqueta un issue.
• on: workflow_call → para reutilizar este workflow desde otros.
• on: push.paths: ['src/**'] → solo si cambian archivos en src/.

Matriz: testear en múltiples versiones/OS

# Matrix: ejecutar el MISMO job en múltiples combinaciones
# Útil para testear en Node 18, 20, 22 y Ubuntu, Windows, macOS
jobs:
  test:
    runs-on: ${{ matrix.os }}      # OS viene de la matriz
    strategy:
      fail-fast: false             # NO cancelar los demás si uno falla
      matrix:
        node-version: [18, 20, 22]  # 3 versiones de Node
        os: [ubuntu-latest, windows-latest, macos-latest]  # 3 OS
        # Total: 9 combinaciones (3 x 3) en paralelo

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

      - run: npm ci
      - run: npm test
        env:
          CI: true                  # flag para que los tests sepan que están en CI

Matrix strategy: 9 combinaciones en paralelo

3.9.4 Pipeline de testing automático en cada PR

El pipeline de testing es el CORAZÓN de CI/CD. En cada Pull Request, GitHub Actions debe correr: lint (calidad de código), tests unit, tests de integración, build, y mostrar el reporte. Si algo falla, el PR no se puede mergear. Es la red de seguridad que evita que bugs lleguen a main. Configurarlo toma 30 minutos y te ahorra meses de bugs en producción.

Pipeline completo de testing en cada PR

# .github/workflows/ci.yml: pipeline profesional
name: CI Pipeline

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main, develop]

jobs:
  # JOB 1: Lint (calidad de código)
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - name: ESLint
        run: npm run lint
      - name: Prettier check
        run: npm run format:check

  # JOB 2: Tests + coverage (paralelo a lint)
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - name: Run tests with coverage
        run: npm run test:coverage
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with: { token: ${{ secrets.CODECOV_TOKEN }} }
      - name: Archive coverage report
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/
          retention-days: 7

  # JOB 3: Build (depende de lint y test)
  build:
    runs-on: ubuntu-latest
    needs: [lint, test]   # espera a que ambos pasen
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - name: Build production bundle
        run: npm run build
        env:
          VITE_API_URL: https://api.miapp.com
      - name: Check bundle size
        run: |
          echo 'Bundle size:'
          du -sh dist/
          # Fallar si el bundle es mayor a 2MB
          SIZE=$(du -sm dist/ | cut -f1)
          if [ $SIZE -gt 2 ]; then
            echo 'Bundle too large!'
            exit 1
          fi

  # JOB 4: Status check (verifica que TODOS pasaron)
  all-checks-passed:
    runs-on: ubuntu-latest
    needs: [lint, test, build]
    if: success()          # solo si los anteriores pasaron
    steps:
      - run: echo 'All checks passed! Ready to merge.'

Pipeline completo: lint, test, build, status check

3.9.5 Deploy automático a Vercel/Netlify con secrets

El deploy automático es la segunda parte de CD (Continuous Deployment). Una vez que los tests pasan y haces merge a main, tu app se deploya automáticamente. Vercel, Netlify, y Railway tienen GitHub Actions oficiales, o puedes usar su integración nativa con GitHub (más fácil). Lo crítico: proteger las API keys y secrets con GitHub Secrets, NUNCA en el código.

Opción 1: Integración nativa (más fácil)

• Vercel: ve a vercel.com, conecta tu repo de GitHub, cada push a main se deploya automáticamente. Sin configurar Actions.
• Netlify: igual, ve a netlify.com, conecta tu repo, cada push a main = deploy automático.
• Railway: para backend, ve a railway.app, conecta tu repo, cada push a main = deploy del backend.
• Ventaja: cero configuración. Desventaja: menos control sobre CUÁNDO deployear.

Opción 2: GitHub Actions con Vercel CLI (más control)

# .github/workflows/deploy.yml: deploy manual con Actions
name: Deploy to Vercel

on:
  push:
    branches: [main]    # solo en merge a main

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

      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }

      - run: npm ci

      - name: Install Vercel CLI
        run: npm install -g vercel@latest

      - name: Pull Vercel environment
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
        env:
            VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
            VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

      - name: Build project
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}

      - name: Deploy to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

      # Si quieres notificar a Slack/Discord/email:
      - name: Notify deploy success
        if: success()
        run: |
          curl -X POST ${{ secrets.DISCORD_WEBHOOK_URL }} \
            -H 'Content-Type: application/json' \
            -d '{"content": "✅ Deploy a producción exitoso: ${{ github.sha }}"}'

      - name: Notify deploy failure
        if: failure()
        run: |
          curl -X POST ${{ secrets.DISCORD_WEBHOOK_URL }} \
            -H 'Content-Type: application/json' \
            -d '{"content": "❌ Deploy FALLÓ en commit ${{ github.sha }}"}'

Deploy a Vercel con notificaciones a Discord

Cómo configurar GitHub Secrets (NUNCA hardcodear API keys)

# Paso 1: ve a tu repo en GitHub > Settings > Secrets and variables > Actions
# Paso 2: 'New repository secret'
# Paso 3: añade los secrets:

# Para Vercel:
#   VERCEL_TOKEN: tu token de Vercel (Settings > Tokens en vercel.com)
#   VERCEL_ORG_ID: el ID de tu org (Project Settings > General)
#   VERCEL_PROJECT_ID: el ID de tu proyecto (Project Settings > General)

# Para Supabase:
#   SUPABASE_URL: la URL de tu proyecto
#   SUPABASE_ANON_KEY: la key pública (anon)
#   SUPABASE_SERVICE_KEY: la key de servicio (SOLO en backend, NUNCA en frontend)

# Para Codecov:
#   CODECOV_TOKEN: el token de codecov.io

# Para Discord/Slack:
#   DISCORD_WEBHOOK_URL: la URL del webhook de tu canal

# En el código, los usas con ${{ secrets.NOMBRE }}:
#   env:
#     API_KEY: ${{ secrets.API_KEY }}

# IMPORTANTE:
#   - NUNCA hagas commit de API keys al repo (aunque sea privado)
#   - NUNCA imprimas secrets en logs (GitHub los enmascara automáticamente, pero no confíes)
#   - Para keys SECRETAS (OpenAI, Stripe, AWS), usa backend con .env
#   - Rota secrets cada 3-6 meses

Configuración correcta de GitHub Secrets

3.9.6 Badges, status checks y el flujo PR → review → merge → deploy

El flujo profesional de CI/CD termina con badges en tu README que muestran el estado de tu pipeline, y un flujo claro: PR → review → status checks pasan → merge a main → deploy automático. Es la última pieza del puzzle: comunicar a tu equipo (y al mundo) que tu código está saludable.

Badges en el README: estado del pipeline a la vista

# README.md: añade badges al inicio

<p align="center">
  <!-- Badge de build status (pasa o falla) -->
  <img src="https://github.com/username/repo/actions/workflows/ci.yml/badge.svg" alt="Build Status">

  <!-- Badge de coverage -->
  <img src="https://codecov.io/gh/username/repo/branch/main/graph/badge.svg" alt="Coverage">

  <!-- Badge de licencia -->
  <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">

  <!-- Badge de versión -->
  <img src="https://img.shields.io/github/v/release/username/repo" alt="Release">

  <!-- Badge de Lighthouse score -->
  <img src="https://img.shields.io/badge/Lighthouse-95%2B-success" alt="Lighthouse">
</p>

# Los badges usan Shields.io o servicios similares (codecov.io, github.com)
# Se actualizan automáticamente según el estado real de tu pipeline.
# Si un badge está rojo, sabes que algo está mal sin abrir GitHub.

# El flujo profesional completo:
# 1. Dev crea branch: git checkout -b feature/login
# 2. Dev hace commits y push: git push origin feature/login
# 3. Dev abre PR en GitHub: 'feature/login' → 'main'
# 4. CI se dispara automáticamente: corre lint + tests + build
# 5. Si CI pasa, badges en verde. Si falla, badges en rojo.
# 6. Reviewer revisa el código y aprueba (o pide cambios)
# 7. Branch protection verifica: tests pasan + review aprobado → permite merge
# 8. Dev mergea: 'Squash and merge' (1 commit limpio)
# 9. Deploy automático a producción (Vercel/Railway)
# 10. Notificación a Slack/Discord: '✅ Deploy a producción exitoso'
# 11. Monitoring (Sentry, LogRocket) verifica que no hay errores

# Tiempo total: 5-10 minutos desde el push hasta producción.

Badges en README + flujo PR → review → merge → deploy

📚 Contenido ampliado

Material adicional, referencias externas verificadas y ejemplos extendidos.