Guía Pro: Crear Pipeline CI/CD con GitHub Actions y Docker

Automatización: La diferencia entre un desarrollador junior y un arquitecto

En el panorama actual del desarrollo de software, la velocidad de entrega no es negociable, pero la calidad tampoco. El despliegue manual por SSH es una receta para el desastre: es propenso a errores humanos, difícil de auditar y lento. Como especialistas, nuestro objetivo debe ser la inmutabilidad y la automatización total.

Si buscas escalar tus proyectos, aprender a crear un pipeline CI/CD con GitHub Actions y Docker es el paso lógico para profesionalizar tu flujo de trabajo. En este artículo, no solo montaremos un sistema de integración y despliegue continuo; construiremos una arquitectura robusta que permite enviar código a producción con solo hacer un git push.

---

Fundamentos del flujo: ¿Por qué Docker + GitHub Actions?

Para entender cómo optimizar nuestra infraestructura, debemos desglosar los componentes clave:

1. GitHub Actions: Nuestro orquestador. Permite disparar flujos de trabajo basados en eventos del repositorio.
2. Docker: El estándar de facto para la contenedorización, garantizando que el entorno de desarrollo sea idéntico al de producción.
3. VPS Linux: Nuestra capa de ejecución, donde alojaremos el runtime de nuestra aplicación.

Tabla Comparativa: Estrategias de Despliegue

Estrategia	Esfuerzo Inicial	Escalabilidad	Seguridad
Despliegue Manual (SCP/SSH)	Bajo	Muy Baja	Muy Baja
Scripts Bash Automatizados	Medio	Media	Media
CI/CD con Docker + Actions	Alto	Alta	Muy Alta

---

Arquitectura del Pipeline: Paso a Paso

Para lograr un despliegue exitoso, seguiremos un flujo lógico:

1. CI (Continuous Integration): Ejecución de tests unitarios y construcción de la imagen.
2. Registry: Almacenamiento de la imagen en Docker Hub o GitHub Container Registry (GHCR).
3. CD (Continuous Deployment): Conexión segura al VPS para pull de la nueva imagen y reinicio del contenedor.

1. Configuración del Workflow en GitHub

Crea el archivo .github/workflows/deploy.yml en tu proyecto. Este archivo define la lógica del pipeline.

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

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Login to DockerHub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: ${{ secrets.DOCKERHUB_USERNAME }}/mi-app:latest

      - name: Deploy to VPS
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            docker pull ${{ secrets.DOCKERHUB_USERNAME }}/mi-app:latest
            docker stop mi-app || true
            docker rm mi-app || true
            docker run -d --name mi-app -p 80:3000 ${{ secrets.DOCKERHUB_USERNAME }}/mi-app:latest

2. Preparación del VPS (Hardening)

No basta con conectar el pipeline. Debes asegurar que el VPS sea capaz de ejecutar la imagen. Asegúrate de tener instalado docker y docker-compose. Además, nunca uses la contraseña de root; utiliza un usuario con privilegios de sudo y autenticación basada en llaves SSH exclusivamente.

---

Mejores Prácticas de Ingeniería

Al crear un pipeline CI/CD con GitHub Actions y Docker, la seguridad es la prioridad número uno. Aquí te listo mis recomendaciones de Arquitecto Senior:

Gestión de Secretos (Secrets)

Nunca incluyas credenciales en tu código. GitHub ofrece los “GitHub Secrets”, donde debes almacenar:

• DOCKERHUB_TOKEN
• SSH_PRIVATE_KEY (La clave privada del par SSH que reside en el VPS)
• VPS_HOST (IP de tu servidor)

Estrategia de Versionado de Imágenes

Evita usar siempre el tag :latest. En entornos de producción, es recomendable usar el SHA del commit (${{ github.sha }}) como tag. Esto permite hacer un Rollback inmediato en caso de que algo falle, simplemente apuntando el contenedor de nuevo a la versión anterior del tag.

---

Errores Comunes y cómo evitarlos (E-E-A-T)

Como ingeniero, he visto muchos pipelines fallar. Aquí los errores más críticos que debes evitar:

1. Imágenes pesadas: No uses imágenes base de tipo node:latest o python:latest. Usa variantes alpine o slim. Esto reduce drásticamente el tiempo de pull en el VPS.
2. Pipeline bloqueante: Si tus tests unitarios fallan, el pipeline debe detenerse inmediatamente (exit 1). Configura tus pasos para que el despliegue no ocurra si el CI falla.
3. SSH Agent bloqueado: A veces, las conexiones SSH desde GitHub pueden fallar si el host no está en los known_hosts. Asegúrate de gestionar la huella digital del servidor correctamente o usa una acción de SSH que ignore la verificación de host de forma segura.
4. Fuga de secretos en logs: Nunca uses echo $SECRET en tus logs de GitHub Actions. Si necesitas depurar, usa masking de secretos.

---

Conclusión: El siguiente nivel

Dominar el pipeline CI/CD no es solo cuestión de eficiencia; es una mentalidad. Al automatizar la infraestructura, liberas tiempo de calidad para centrarte en lo que realmente importa: escribir código de alto impacto y resolver problemas complejos.

Si te ha gustado esta guía, te invito a explorar más contenido técnico sobre arquitectura y desarrollo en mi portafolio. En izerick.dev, comparto constantemente recursos sobre cómo integrar IA en el flujo de trabajo moderno y optimizar arquitecturas de alto rendimiento.

¿Tienes dudas sobre cómo implementar esto en tu stack específico? Escríbeme o revisa mis otros artículos en el blog. La infraestructura es la columna vertebral de tu éxito. ¡Manos a la obra!