Construir Pipeline CI/CD

Diseña e implementa pipelines de integración y despliegue continuo de nivel productivo con GitHub Actions.

Cuándo Usar

• Al configurar pruebas y despliegues automáticos para un proyecto nuevo
• Al migrar de Jenkins, Travis CI o CircleCI a GitHub Actions
• Al implementar construcciones matriciales en múltiples plataformas o versiones de lenguaje
• Al agregar caché de compilación para acelerar el tiempo de ejecución de CI/CD
• Al crear pipelines multietapa con despliegues específicos por entorno
• Al implementar análisis de seguridad y puertas de calidad de código

Entradas

• Requerido: Repositorio con código para probar/construir/desplegar
• Requerido: Directorio de flujos de trabajo de GitHub Actions (

  .github/workflows/

  )
• Opcional: Secretos para destinos de despliegue (AWS, Azure, registros Docker)
• Opcional: Configuración de ejecutores autohospedados para construcciones especializadas
• Opcional: Reglas de protección de rama y verificaciones de estado requeridas

Procedimiento

Paso 1: Crear la Estructura Base del Flujo de Trabajo

Crea

.github/workflows/ci.yml

con la configuración de disparadores y la estructura básica de trabajos.

name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
  workflow_dispatch:  # Manual trigger

env:
  NODE_VERSION: '18'
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  lint:
    name: Lint Code
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run ESLint
        run: npm run lint

      - name: Check formatting
        run: npm run format:check

Esperado: Archivo de flujo de trabajo creado con sintaxis YAML correcta, disparadores configurados y trabajo básico de lint definido.

En caso de fallo: Valida la sintaxis YAML con

yamllint .github/workflows/ci.yml

. Comprueba la indentación (usa espacios, no tabuladores). Verifica que las versiones de acciones sean actuales revisando el Marketplace de GitHub.

Paso 2: Implementar la Estrategia de Construcción Matricial

Agrega construcciones matriciales para probar en múltiples plataformas, versiones de lenguaje o configuraciones.

  test:
    name: Test (${{ matrix.os }}, Node ${{ matrix.node }})
    runs-on: ${{ matrix.os }}
    needs: lint
    strategy:
      fail-fast: false  # Continue testing other matrix combinations on failure
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: ['16', '18', '20']
        exclude:
          - os: macos-latest
            node: '16'  # Skip old Node on macOS

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests with coverage
        run: npm run test:coverage

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        if: matrix.os == 'ubuntu-latest' && matrix.node == '18'
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          files: ./coverage/lcov.info
          fail_ci_if_error: true

Esperado: La matriz genera 8 trabajos paralelos (3 SO × 3 versiones de Node - 1 exclusión). Todas las pruebas pasan entre plataformas. El informe de cobertura se sube desde un único trabajo canónico.

En caso de fallo: Si ocurren errores de sintaxis matricial, verifica la indentación correcta y la notación de arrays. Para pruebas inestables, agrega lógica de reintento con

uses: nick-invision/retry@v2

. Para fallos específicos de plataforma, agrega condicionales de SO o amplía las exclusiones.

Paso 3: Configurar el Caché de Dependencias y la Gestión de Artefactos

Optimiza la velocidad de compilación con caché inteligente y preserva los artefactos de construcción.

  build:
    name: Build Application
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - name: Cache build output
        uses: actions/cache@v3
        with:
          path: |
            .next/cache
            dist/
            build/
          key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}-
            ${{ runner.os }}-build-

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build
        env:
          NODE_ENV: production

      - name: Upload build artifacts
        uses: actions/upload-artifact@v3
        with:
          name: dist-${{ github.sha }}
          path: |
            dist/
            build/
          retention-days: 7
          if-no-files-found: error

Esperado: La primera ejecución descarga dependencias (lenta), las ejecuciones posteriores restauran desde caché (rápida). Los artefactos de construcción se suben exitosamente con nombres únicos basados en SHA.

En caso de fallo: Si el caché falla frecuentemente, verifica que la clave incluya todos los hashes de archivos relevantes. Para fallos de subida, comprueba que la ruta existe y los patrones glob coinciden con la salida real. Verifica que

retention-days

cumple las políticas de la organización.

Paso 4: Implementar Análisis de Seguridad y Puertas de Calidad

Agrega análisis de vulnerabilidades de seguridad y aplicación de calidad de código.

  security:
    name: Security Scan
    runs-on: ubuntu-latest
    needs: lint
    permissions:
      security-events: write  # Required for uploading SARIF results
    steps:
      - uses: actions/checkout@v4

      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          scan-ref: '.'
          format: 'sarif'
          output: 'trivy-results.sarif'
          severity: 'CRITICAL,HIGH'

      - name: Upload Trivy results to GitHub Security
        uses: github/codeql-action/upload-sarif@v2
        if: always()  # Upload even if scan finds vulnerabilities
        with:
          sarif_file: 'trivy-results.sarif'

      - name: Dependency audit
        run: npm audit --audit-level=high
        continue-on-error: true  # Don't fail build, but show warnings

      - name: Check for leaked secrets
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.repository.default_branch }}
          head: HEAD

Esperado: Los análisis de seguridad se completan y los resultados se suben a la pestaña de Seguridad de GitHub. Las vulnerabilidades críticas bloquean la fusión si la protección de rama está configurada. No se detectan secretos en los commits.

En caso de fallo: Para falsos positivos, crea el archivo

.trivyignore

con IDs de CVE y justificaciones. Para fallos de auditoría, revisa las sugerencias de

npm audit fix

. Para falsos positivos de detección de secretos, agrega patrones a la lista de exclusión de

.trufflehog.yml

.

Paso 5: Configurar Despliegues Específicos por Entorno

Configura etapas de despliegue con reglas de protección de entorno y puertas de aprobación.

  deploy-staging:
    name: Deploy to Staging
    runs-on: ubuntu-latest
    needs: [build, security]
    if: github.ref == 'refs/heads/develop'
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v3
        with:
          name: dist-${{ github.sha }}
          path: ./dist

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_STAGING }}
          aws-region: us-east-1

      - name: Deploy to S3
        run: |
          aws s3 sync ./dist s3://${{ secrets.S3_BUCKET_STAGING }} --delete
          aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DIST_STAGING }} --paths "/*"

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: [build, security]
    if: github.ref == 'refs/heads/main'
    environment:
      name: production
      url: https://example.com
    steps:
      - name: Download build artifacts
        uses: actions/download-artifact@v3
        with:
          name: dist-${{ github.sha }}
          path: ./dist

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_PRODUCTION }}
          aws-region: us-east-1

      - name: Deploy to S3 with blue-green
        run: |
          # Deploy to new version
          aws s3 sync ./dist s3://${{ secrets.S3_BUCKET_PRODUCTION }}/releases/${{ github.sha }} --delete

          # Update symlink to new version
          aws s3 cp s3://${{ secrets.S3_BUCKET_PRODUCTION }}/releases/${{ github.sha }} s3://${{ secrets.S3_BUCKET_PRODUCTION }}/current --recursive

          # Invalidate CloudFront
          aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DIST_PRODUCTION }} --paths "/*"

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: ./dist/**/*
          generate_release_notes: true

Esperado: Staging se despliega automáticamente en la rama develop. Producción requiere aprobación manual (configurada en la configuración de Entornos de GitHub). La invalidación de CloudFront borra el caché de CDN. Se crea un release para los commits etiquetados.

En caso de fallo: Para errores de credenciales AWS, verifica que la relación de confianza OIDC permita

role-to-assume

. Para fallos de sincronización S3, comprueba las políticas de bucket y los permisos IAM. Para problemas de aprobación de entorno, verifica las reglas de protección en Configuración > Entornos.

Paso 6: Agregar Notificaciones e Integración de Monitoreo

Integra notificaciones de Slack, seguimiento de despliegues y monitoreo de rendimiento.

  notify:
    name: Notify Results
    runs-on: ubuntu-latest
    needs: [deploy-staging, deploy-production]
    if: always()  # Run even if previous jobs fail
    steps:
      - name: Check job status
        id: status
        run: |
          if [ "${{ needs.deploy-production.result }}" == "success" ]; then
            echo "status=success" >> $GITHUB_OUTPUT
            echo "color=#00FF00" >> $GITHUB_OUTPUT
          else
            echo "status=failure" >> $GITHUB_OUTPUT
            echo "color=#FF0000" >> $GITHUB_OUTPUT
          fi

      - name: Send Slack notification
        uses: slackapi/slack-github-action@v1.24.0
        with:
          payload: |
            {
              "text": "Deployment ${{ steps.status.outputs.status }}",
              "blocks": [
                {
                  "type": "header",
                  "text": {
                    "type": "plain_text",
                    "text": "🚀 Deployment Status: ${{ steps.status.outputs.status }}"
                  }
                },
                {
                  "type": "section",
                  "fields": [
                    {"type": "mrkdwn", "text": "*Repository:*\n${{ github.repository }}"},
                    {"type": "mrkdwn", "text": "*Branch:*\n${{ github.ref_name }}"},
                    {"type": "mrkdwn", "text": "*Commit:*\n${{ github.sha }}"},
                    {"type": "mrkdwn", "text": "*Actor:*\n${{ github.actor }}"}
                  ]
                },
                {
                  "type": "actions",
                  "elements": [
                    {
                      "type": "button",
                      "text": {"type": "plain_text", "text": "View Workflow"},
                      "url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
                    }
                  ]
                }
              ]
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
          SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK

      - name: Record deployment in Datadog
        if: steps.status.outputs.status == 'success'
        run: |
          curl -X POST "https://api.datadoghq.com/api/v1/events" \
            -H "Content-Type: application/json" \
            -H "DD-API-KEY: ${{ secrets.DD_API_KEY }}" \
            -d @- <<EOF
          {
            "title": "Deployment: ${{ github.repository }}",
            "text": "Deployed commit ${{ github.sha }} to production",
            "tags": ["env:production", "service:${{ github.event.repository.name }}"],
            "alert_type": "info"
          }
          EOF

Esperado: Slack recibe una notificación formateada con el estado del despliegue, detalles del repositorio y un enlace clicable al flujo de trabajo. El evento de Datadog se registra para despliegues exitosos a producción con las etiquetas apropiadas.

En caso de fallo: Para fallos de Slack, verifica que la URL del webhook sea válida y que el espacio de trabajo permita webhooks entrantes. Prueba con

curl -X POST $SLACK_WEBHOOK_URL -d '{"text":"test"}'

. Para fallos de Datadog, verifica que la clave API tenga permisos de envío de eventos.

Validación

• La sintaxis del flujo de trabajo se valida con

  yamllint

  o el editor de flujos de trabajo de GitHub
• Todos los trabajos tienen dependencias explícitas (

  needs:

  ) para controlar el orden de ejecución
• Las construcciones matriciales cubren todas las plataformas y versiones de destino
• El caché reduce el tiempo de construcción en más del 50% en ejecuciones posteriores
• Los secretos se almacenan en Secretos de GitHub, nunca codificados en los archivos de flujo de trabajo
• Los análisis de seguridad suben resultados a la pestaña de Seguridad de GitHub
• Las reglas de protección de entorno requieren aprobación para despliegues a producción
• Los despliegues fallidos no dejan el sistema en un estado inconsistente
• Las notificaciones llegan a los canales apropiados (Slack, correo, herramientas de monitoreo)
• El flujo de trabajo se completa en menos de 10 minutos para cambios típicos

Errores Comunes

• Clave de caché demasiado amplia: Usar

  ${{ runner.os }}-build-

  como clave de caché causa aciertos falsos cuando cambian las dependencias. Incluye

  hashFiles('**/package-lock.json')

  en la clave.

• Colisiones de nombres de artefactos: Usar nombres estáticos de artefactos como

  dist

  causa sobreescrituras en construcciones concurrentes. Incluye

  ${{ github.sha }}

  o

  ${{ matrix.os }}-${{ matrix.node }}

  en los nombres.

• Secretos en registros: Evita

  echo $SECRET

  u comandos similares. GitHub enmascara los secretos registrados, pero los valores derivados pueden filtrarse. Usa

  ::add-mask::

  para secretos dinámicos.

• Permisos insuficientes: El

  GITHUB_TOKEN

  predeterminado tiene permisos limitados. Agrega un bloque explícito

  permissions:

  para eventos de seguridad, paquetes, issues, etc.

• Condicionales faltantes: Los trabajos se ejecutan en todos los disparadores a menos que estén protegidos con

  if: github.ref == 'refs/heads/main'

  . Previene despliegues accidentales a producción desde PRs.

• Sin estrategia de reversión: Los fallos de despliegue dejan el sistema en estado roto. Implementa despliegues azul-verde o canary con reversión automática ante fallos en las verificaciones de salud.

• Valores codificados: El flujo de trabajo contiene URLs, nombres de bucket o endpoints de API específicos del entorno. Usa variables de entorno y Secretos de GitHub.

• Sin límites de tiempo de espera: Los trabajos se cuelgan indefinidamente en problemas de red o bucles infinitos. Agrega

  timeout-minutes: 15

  a todos los trabajos.

Habilidades Relacionadas

• setup-github-actions-ci

  - Configuración inicial de GitHub Actions para paquetes R y proyectos básicos

• commit-changes

  - Integración correcta del flujo de trabajo Git con disparadores de CI/CD

• configure-git-repository

  - Configuración del repositorio y reglas de protección de rama

• setup-container-registry

  - Construcciones de imágenes Docker en pipelines CI/CD

• implement-gitops-workflow

  - Integración de ArgoCD/Flux con CI/CD