CI/CD con GitHub Actions: la guía completa 2026

La integración continua y el despliegue continuo (CI/CD) son la columna vertebral de cualquier equipo moderno de desarrollo. En este post vas a aprender a armar un pipeline profesional con GitHub Actions en menos de una hora, desde lo más básico hasta técnicas avanzadas que usan los equipos senior.

Qué es CI/CD y por qué importa

CI/CD significa Continuous Integration / Continuous Delivery. La convención más extendida (GitHub, GitLab, AWS) usa Delivery para la segunda D: el código se valida automáticamente y queda listo para desplegar a producción de forma confiable. Continuous Deployment es una variante más agresiva donde cada commit que pasa los checks va directo a producción sin gate humano — es un subconjunto de Delivery.

¿Por qué es importante? Tres razones principales:

1. Reducir bugs en producción: el código se testea en cada push, no cuando alguien se acuerda.
2. Desplegar más rápido: sin CI/CD, un deploy puede llevar horas de clicks manuales. Con automation, minutos.
3. Confianza para iterar: los developers pueden hacer cambios sin miedo porque saben que el pipeline los va a agarrar si rompen algo.

GitHub Actions es la opción más simple para empezar porque viene incluido en cualquier repo de GitHub sin instalar nada adicional.

Tu primer workflow

Todo workflow de GitHub Actions vive en un archivo YAML dentro de la carpeta .github/workflows de tu repo. Vamos a crear el primero paso a paso.

Primero, la estructura mínima de un workflow:

name: CI Pipeline
on:
  push:
    branches: [main]

Este bloque on: define cuándo se dispara el workflow. En este caso corre cada vez que alguien hace push a la rama main. Ahora agregamos los jobs:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm test

Cada step usa actions/checkout@v4 para clonar tu código. Después setup-node@v4 instala Node.js versión 20. Los run ejecutan comandos en la shell: npm ci instala dependencias desde package-lock.json de forma reproducible, y npm test corre tus tests.

El runner ubuntu-latest es una VM Ubuntu que GitHub te da gratis. Hay runners para Windows y macOS también, pero Ubuntu es el más rápido y barato.

Secrets y variables de entorno

Cuando necesitas API keys, tokens de deploy o contraseñas, nunca las pongas en el código. usa los secrets de GitHub.

Para agregar un secret andá a Settings > Secrets and variables > Actions > New repository secret. Después lo usas así:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        run: |
          echo "Deploying to production..."
          curl -X POST https://api.example.com/deploy 
            -H "Authorization: Bearer ${{ secrets.DEPLOY_TOKEN }}"
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Los secrets están enmascarados en los logs automáticamente. Si por error hacés echo ${{ secrets.DEPLOY_TOKEN }}, GitHub muestra *** en lugar del valor real. Esto evita que un log commit accidental exponga tus credenciales.

Triggers avanzados

Además de push y pull_request, hay muchos otros disparadores:

on:
  workflow_dispatch:  # boton manual en la UI de GitHub
  schedule:
    - cron: '0 6 * * *'  # todos los dias a las 6am UTC
  release:
    types: [published]  # cuando se publica un release
  pull_request:
    types: [closed]  # cuando se cierra un PR (util para limpieza)

workflow_dispatch es muy útil para deploys manuales. Definís inputs y el usuario los completa antes de correr el workflow:

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Ambiente de deploy'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

Cache de dependencias

Las dependencias de Node.js pesan cientos de MB. Si las descargas en cada build, el pipeline se vuelve lento. activa el cache:

      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          cache: 'npm'

La opción cache: 'npm' del setup-node@v4 cachea el download cache de npm (~/.npm/_cacache), indexado por el hash de package-lock.json. Si cambia el lockfile se regenera, si no se reusa. Esto hace que la mayoría de los builds sean 5-10x más rápidos y, a diferencia de cachear node_modules directamente, es seguro con npm ci y no rompe binarios nativos.

Matrix builds

Si tu código corre en múltiples versiones de Node, puedes testear todas en paralelo:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

Esto crea 3 jobs en paralelo, uno por cada versión de Node. Si alguno falla, el workflow completo falla.

Artifacts y reportes

Para guardar logs de tests, coverage reports o binarios compilados, usa artifacts:

- name: Test
  run: npm test -- --coverage
- uses: actions/upload-artifact@v4
  with:
    name: coverage-report
    path: coverage/

Después puedes descargar el artifact desde la UI de GitHub Actions. Muy útil para debuggear tests que fallan solo en CI.

Triggers de seguridad

La integración canónica con Dependabot no usa repository_dispatch (ese evento es 100% manual vía API), sino que Dependabot abre un PR automático cuando detecta una vulnerabilidad o update:

on:
  pull_request:
    branches: [main]
    paths: ['package-lock.json']
    # Filtrá por autor Dependabot si quieres reaccionar solo a sus PRs:
    #   if: github.actor == 'dependabot[bot]'

Ese PR dispara on: pull_request y tu CI corre los tests contra la versión parcheada antes de mergear. Combinado con paths: ['package-lock.json'] o un if: github.actor == 'dependabot[bot]', limitás el workflow a los PRs automáticos de Dependabot y respondés a vulnerabilidades en minutos, no en días.

Troubleshooting

El error más común es no ver los logs porque el step falló silenciosamente. Siempre revisa la pestaña Actions > tu workflow > job específico > step que falló. El log completo está ahí.

Si el build pasa en tu laptop pero falla en CI, casi siempre es:
– Diferencia de versión de Node entre local y CI
– Variables de entorno que tienes local pero no en secrets
– Permisos de filesystem (CI corre como root pero tu app espera otro user)

Para debugging más fino, puedes usar tmate o ssh-action para abrir una shell interactiva al runner, pero ojo que consume minutos facturables en runners privados.

Preguntas frecuentes

Lee también

• Guía Fedora 44: Novedades, Instalación y Upgrade para Sysadmins Linux
• Configura VLANs en Linux con nmcli: Guía paso a paso para sysadmins
• Protege tu SSH: Guía esencial para configurar Fail2ban en Linux
• Guía Definitiva: Configura Kubernetes con kubeadm en Ubuntu para Sysadmins Linux
• Configura Prometheus y Grafana: Guía DevOps para SysAdmins Linux