CI/CD con GitHub Actions: del commit a producción

El tiempo entre que un desarrollador escribe código y ese código llega a los usuarios finales es uno de los indicadores más importantes de la eficiencia de un equipo de ingeniería. Hace diez años, un ciclo de despliegue de semanas era habitual en empresas grandes. Hoy, los equipos más competitivos despliegan varias veces al día con total confianza porque han construido pipelines de integración y entrega continua que verifican, validan y despliegan el código de forma automática.

GitHub Actions, lanzado en 2019, democratizó la CI/CD al integrarla directamente en la plataforma donde los equipos ya gestionan su código. No hay que configurar servidores Jenkins, mantener instalaciones de GitLab CI o pagar por integraciones externas. El pipeline vive en el mismo repositorio que el código, se revisa junto a los pull requests y comparte el historial de versiones con la aplicación.

Esta guía cubre desde los conceptos fundamentales de GitHub Actions hasta la construcción de pipelines de producción: tests automatizados, análisis de seguridad, construcción de imágenes Docker, despliegue en Kubernetes o en servidores clásicos, y las mejores prácticas que distinguen a los pipelines robustos de los que fallan en el peor momento posible.

Conceptos fundamentales de GitHub Actions

GitHub Actions se estructura alrededor de cuatro conceptos clave que conviene entender bien antes de escribir tu primer workflow. Un workflow es un proceso automatizado definido en un archivo YAML dentro del directorio .github/workflows/ de tu repositorio. Cada workflow se compone de uno o más jobs que se ejecutan en paralelo (por defecto) o de forma secuencial (si defines dependencias con needs:). Cada job contiene una secuencia de steps, y cada step ejecuta un comando de shell o una action reutilizable.

Eventos que disparan workflows

Los workflows se activan mediante eventos. Los más comunes son push (cuando se sube código a una rama), pull_request (cuando se abre, actualiza o fusiona un PR), schedule (según un cron), workflow_dispatch (manualmente desde la interfaz web o la API) y release (cuando se publica una nueva versión). Puedes filtrar por rama, etiqueta o ruta de archivos: por ejemplo, ejecutar los tests solo cuando cambien archivos dentro de src/, o desplegar solo cuando se hace push a main.

Runners: dónde se ejecuta tu pipeline

Los jobs se ejecutan en runners, que son máquinas virtuales proporcionadas por GitHub (hosted runners) o servidores propios (self-hosted runners). GitHub ofrece runners Ubuntu, Windows y macOS. Los Ubuntu son los más populares por su precio (gratuitos para repositorios públicos, con créditos para privados) y rendimiento. Para necesidades especiales (hardware específico, redes privadas, mayor RAM) puedes configurar self-hosted runners en tus propias máquinas o en tu infraestructura cloud.

Tu primer workflow: tests automáticos en cada push

El workflow más básico y valioso ejecuta los tests de tu proyecto en cada push y en cada pull request. Para una aplicación Node.js, el archivo .github/workflows/test.yml contendría: el evento on push y pull_request para todas las ramas, un job test que ejecuta en ubuntu-latest, y tres steps: checkout del código con actions/checkout, configuración de Node con actions/setup-node especificando la versión, instalación de dependencias con npm ci y ejecución de tests con npm test.

Con este workflow, cada vez que alguien sube código o abre un pull request, GitHub ejecuta los tests automáticamente y muestra el resultado directamente en la interfaz del PR. Un PR con tests en rojo no puede fusionarse si configuras las branch protection rules adecuadas. Esto elimina la práctica de fusionar código sin verificar que no rompe nada, uno de los errores más costosos en equipos de desarrollo.

Matriz de versiones: testa en múltiples entornos simultáneamente

Una de las características más potentes de GitHub Actions es la estrategia de matriz (matrix strategy). Te permite ejecutar el mismo job con diferentes combinaciones de variables sin duplicar código. Para una librería Python que debe funcionar en Python 3.9, 3.10, 3.11 y 3.12, defines matrix: python-version: [3.9, 3.10, 3.11, 3.12] y GitHub Actions ejecuta cuatro jobs en paralelo, uno por cada versión.

Las matrices pueden ser multidimensionales: por ejemplo, testear en tres versiones de Node.js y en Ubuntu y Windows simultáneamente, generando seis jobs en paralelo. El tiempo total de ejecución no aumenta linealmente con el número de combinaciones porque todas se ejecutan en paralelo (hasta el límite de concurrencia de tu plan). Esta capacidad es especialmente valiosa para librerías de código abierto y para aplicaciones que deben funcionar en múltiples sistemas operativos.

Actions reutilizables: el ecosistema que acelera tu pipeline

GitHub Marketplace alberga miles de actions creadas por la comunidad y por proveedores cloud que puedes usar como steps en tus workflows. Algunas de las más utilizadas en entornos empresariales son: actions/checkout (checkout de código), actions/setup-node, actions/setup-python, actions/setup-java (configurar entornos de lenguaje), docker/login-action y docker/build-push-action (construcción y publicación de imágenes Docker), aws-actions/configure-aws-credentials (autenticación con AWS mediante OIDC), y aquasecurity/trivy-action (análisis de vulnerabilidades en imágenes Docker).

Al usar una action de terceros, es buena práctica fijarla a un hash de commit específico (uses: actions/checkout@v4.1.1 o con SHA) en lugar de usar una etiqueta mutable como @main. Esto protege tu pipeline de cambios inesperados en la action que podrían romper tu pipeline o, en un escenario de supply chain attack, introducir código malicioso.

Secretos y variables de entorno: gestión segura de credenciales

Los pipelines de CI/CD necesitan credenciales: claves API, contraseñas de bases de datos, tokens de acceso a registros Docker, claves SSH para despliegue. GitHub Actions proporciona un sistema de secretos cifrados accesibles como variables de entorno en los workflows. Los secretos se definen en Settings > Secrets and variables > Actions del repositorio (o a nivel de organización para compartirlos entre repositorios).

Una práctica cada vez más extendida es reemplazar las claves de acceso de larga duración (AWS Access Keys, tokens estáticos) por autenticación OIDC (OpenID Connect). Con OIDC, GitHub Actions obtiene un token temporal de corta duración que AWS, Azure o GCP validan directamente, sin necesidad de almacenar claves estáticas como secretos. Esto elimina el riesgo de filtración de credenciales de larga duración y facilita la rotación.

Pipeline completo: de commit a imagen Docker en registro privado

Un pipeline de producción típico para una aplicación containerizada encadena varios stages. Primero, ejecuta los tests unitarios e de integración. Si los tests pasan, construye la imagen Docker con el tag del commit SHA para trazabilidad. A continuación, ejecuta un análisis de seguridad de la imagen con Trivy para detectar vulnerabilidades conocidas en las dependencias. Si el análisis no reporta vulnerabilidades críticas, publica la imagen en Amazon ECR, GitHub Container Registry o Docker Hub. Finalmente, actualiza el manifiesto de Kubernetes o dispara el despliegue en la plataforma destino.

1. Stage test: checkout + setup entorno + npm ci + npm test (con cobertura).
2. Stage build: docker/build-push-action con cache de capas (cache-from/cache-to) para acelerar builds.
3. Stage scan: aquasecurity/trivy-action con severity CRITICAL,HIGH y exit-code 1 para detener el pipeline si hay CVEs críticos.
4. Stage push: docker/login-action + docker/build-push-action con push: true y tags versionados.
5. Stage deploy: actualización del deployment en Kubernetes vía kubectl set image o ArgoCD sync.
6. Stage notify: notificación a Slack o Teams con el resultado del despliegue y el enlace al build.

Despliegue en servidores con SSH

No todas las empresas usan Kubernetes o servicios cloud gestionados. Muchas aplicaciones se despliegan en servidores VPS o bare metal. GitHub Actions puede manejar este escenario perfectamente usando una action SSH como appleboy/ssh-action o configurando una clave SSH privada como secreto y usando el cliente SSH nativo del runner de Ubuntu.

El flujo típico consiste en: añadir la clave SSH privada al agente SSH del runner, conectarse al servidor de producción y ejecutar el script de despliegue (git pull, docker-compose pull y up, o cualquier otro mecanismo que uses). Para despliegues con cero tiempo de caída (zero-downtime deployment), el script en el servidor puede implementar una estrategia blue-green básica o usar las capacidades de recarga sin caída de NGINX y gunicorn.

Entornos y aprobaciones manuales

GitHub Actions soporta el concepto de entornos (environments) con reglas de protección que requieren aprobación manual antes de desplegar. Puedes configurar que el despliegue en producción quede bloqueado hasta que uno o más revisores designados lo aprueben desde la interfaz web. Esto proporciona un control de cambios formal sin sacrificar la automatización: el pipeline hace todo el trabajo pesado (tests, build, análisis de seguridad) pero el paso final requiere supervisión humana.

Los entornos también permiten definir secretos específicos por entorno (las credenciales de staging son distintas a las de producción) y tiempos de espera máximos antes de cancelar el despliegue pendiente de aprobación. Esta funcionalidad cubre el 80% de los requisitos de control de cambios que tienen las empresas con procesos de gestión del cambio formales, sin necesidad de herramientas externas.

Caché y artefactos: acelera tus pipelines

En proyectos grandes, instalar dependencias desde cero en cada ejecución puede consumir varios minutos. La action actions/cache permite cachear directorios entre ejecuciones usando una clave basada en el hash del archivo de dependencias (package-lock.json, requirements.txt, pom.xml). Si el archivo de dependencias no ha cambiado, el directorio node_modules, .venv o ~/.m2 se restaura desde caché en segundos en lugar de descargarse de internet.

Los artefactos (actions/upload-artifact y download-artifact) permiten compartir ficheros entre jobs del mismo workflow o preservarlos para descarga posterior. Los casos de uso habituales son: pasar la aplicación compilada del job de build al job de despliegue, preservar los informes de cobertura de tests para visualizarlos en la interfaz de GitHub, o almacenar los logs de tests fallidos para facilitar la depuración.

Análisis de seguridad y calidad de código integrados

GitHub Actions se integra perfectamente con herramientas de análisis estático de código. GitHub Code Scanning, basado en CodeQL (desarrollado por GitHub), analiza el código fuente en busca de vulnerabilidades de seguridad como inyección SQL, XSS, deserialización insegura y docenas de otros patrones. Se configura con un workflow de pocas líneas y los resultados aparecen directamente en la pestaña Security del repositorio y como comentarios en los pull requests.

• CodeQL: análisis semántico de código para detección de vulnerabilidades de seguridad. Soporta JavaScript, Python, Java, C#, Go, Ruby y más.
• Dependabot: no es un workflow pero se complementa con Actions. Abre PRs automáticos para actualizar dependencias con CVEs conocidos.
• OSSF Scorecard: evalúa la postura de seguridad del repositorio (uso de secretos, permisos de workflows, dependencias fijadas) y publica una puntuación.
• SonarCloud: análisis de calidad de código (deuda técnica, code smells, duplicaciones) con integración nativa en GitHub Actions.
• Snyk: análisis de vulnerabilidades en dependencias de aplicación e imágenes Docker con remediación sugerida.

Workflows reutilizables: DRY para pipelines

Si tienes múltiples repositorios con pipelines similares (todos los microservicios de una empresa siguen el mismo proceso de build, test y despliegue), los workflows reutilizables (reusable workflows) te permiten centralizar la lógica del pipeline. Un repositorio central define el workflow genérico como callable (on: workflow_call) y cada repositorio de microservicio lo invoca pasando solo los parámetros específicos (nombre de la imagen, entorno destino, etc.).

Esta arquitectura facilita enormemente el mantenimiento: cuando cambias el proceso de seguridad (por ejemplo, añades un nuevo scanner de vulnerabilidades), lo actualizas en un único lugar y todos los repositorios adoptan el cambio. Sin workflows reutilizables, ese cambio implicaría modificar docenas de archivos YAML repartidos por todos los repositorios, con el riesgo de inconsistencias y olvidos.

Optimización de costes y concurrencia

En repositorios con mucha actividad, los minutos de GitHub Actions pueden suponer un gasto significativo si no se gestionan adecuadamente. Varias estrategias ayudan a controlar los costes: usar paths filters para ejecutar solo los jobs relevantes cuando cambian archivos específicos, configurar concurrency groups para cancelar ejecuciones antiguas cuando llega una nueva del mismo PR, usar runners de Ubuntu (más baratos que Windows o macOS), y diseñar los jobs para que fallen rápido (fail fast) moviendo los checks más rápidos al principio.

La configuración de concurrency es especialmente valiosa. Si un desarrollador hace push repetidamente en una rama de feature mientras trabaja, sin concurrencia configurada se acumularían múltiples ejecuciones del pipeline. Con concurrency: group: ${{ github.ref }} y cancel-in-progress: true, cada nuevo push cancela el pipeline del push anterior, ejecutando siempre solo el más reciente y ahorrando minutos.

Un pipeline de CI/CD no es un lujo técnico; es la red de seguridad que permite a los equipos moverse rápido sin romper cosas. Cada minuto invertido en construirlo bien se recupera multiplicado en confianza y velocidad de entrega.

Errores comunes en pipelines de producción

• Usar latest en tags de actions o imágenes: fija siempre versiones concretas para builds reproducibles.
• Secretos hardcodeados en el YAML: usa siempre secrets.TU_SECRETO, nunca valores literales en el archivo de workflow.
• Permisos excesivos en GITHUB_TOKEN: especifica permissions: con el mínimo necesario (contents: read, packages: write, etc.).
• No validar el YAML antes de hacer push: usa la extensión de GitHub Actions para VS Code o actionlint localmente.
• Pipelines sin timeouts: un job colgado puede bloquear el pipeline indefinidamente. Configura timeout-minutes en cada job.
• Ignorar los fallos en steps de notificación: usa if: always() en steps de notificación para que se ejecuten aunque el pipeline falle.

Conclusión: empieza simple y escala gradualmente

La mejor estrategia para adoptar GitHub Actions en un equipo es empezar por el workflow más simple y valioso: ejecutar los tests en cada pull request. Una vez ese workflow esté funcionando y el equipo confíe en él, añade la construcción de la imagen Docker. Luego, el análisis de seguridad. Después, el despliegue automatizado en staging. Finalmente, el despliegue en producción con aprobación manual.

Cada paso añade valor concreto y aumenta la confianza del equipo en el pipeline. No intentes construir el pipeline perfecto desde el primer día: un pipeline básico que funciona siempre es infinitamente más valioso que uno complejo que falla de forma imprevisible. Documenta el workflow en el propio repositorio, revísalo junto al código en los pull requests y trátalo como el activo de ingeniería que es.