Test Deploy

Introduccion

Este proyecto es un laboratorio de aprendizaje para implementar un pipeline de CI/CD completo usando GitHub Actions, Docker y despliegue automatizado en un servidor remoto.

Contribuir al proyecto? Consulta la Guia de Contribucion para conocer el flujo de trabajo con GitFlow.

El objetivo fue construir desde cero un sistema que permita:

• Desplegar automaticamente al hacer push a main
• Versionar la aplicacion con tags de Git
• Realizar rollbacks a versiones anteriores
• Validar cambios antes de mergear a main
• Aplicar buenas practicas de seguridad
• Recibir notificaciones en Telegram cuando hay fallos

A lo largo del desarrollo se encontraron multiples problemas que fueron resueltos iterativamente, documentados en la seccion Problemas Resueltos.

Que se aprendio

CI/CD con GitHub Actions

• Crear workflows que se disparan en push, tags y PRs
• Usar workflow_dispatch para ejecucion manual con parametros
• Encadenar jobs con dependencias (needs)
• Usar condicionales (if) para controlar ejecucion
• Pasar datos entre steps con $GITHUB_OUTPUT
• Crear Composite Actions para reutilizar codigo entre workflows
• Integrar notificaciones a Telegram via webhooks de n8n

Docker y Container Registry

• Construir imagenes Docker optimizadas (Alpine, multi-stage)
• Publicar imagenes en GitHub Container Registry (ghcr.io)
• Crear multiples tags por imagen (version, sha, branch)
• Sistema de capas de Docker y como afecta el espacio
• Ejecutar contenedores como usuario no-root

Git y Versionado

• Crear tags automaticamente desde workflows
• Proteger ramas con branch protection rules
• Validar versiones antes de permitir merge
• Configurar Git con diferentes usuarios por carpeta (includeIf)
• Configurar multiples llaves SSH por repositorio

Despliegue y Operaciones

• Deploy via SSH desde GitHub Actions
• Integracion con Traefik como reverse proxy
• Health checks para verificar despliegues
• Rollback a versiones anteriores
• Limpieza de imagenes Docker no utilizadas

Arquitectura

Flujo de Deploy

Flujo de Rollback

Flujo de Pull Request

Problemas Resueltos

1. SSH Key Verification Failed

Problema: Al clonar el repo desde el servidor, fallaba con "Host key verification failed".

Causa: El servidor no tenia configurada la llave SSH para GitHub.

Solucion: Cambiar de SSH a HTTPS para el clone:

# Antes (fallaba)
git clone git@github.com:user/repo.git

# Despues (funciona)
git clone https://github.com/user/repo.git

2. Permission Denied en Docker

Problema: docker compose fallaba con "permission denied" al socket de Docker.

Causa: El usuario SSH no estaba en el grupo docker.

Solucion: Agregar usuario al grupo docker en el servidor:

sudo usermod -aG docker $USER
newgrp docker

3. Health Check Fallaba con Contenedor Corriendo

Problema: El health check a localhost:3000 fallaba aunque el contenedor estaba corriendo.

Causa: Con Traefik, el puerto 3000 no esta expuesto al host, solo accesible via la red de Docker.

Solucion: Cambiar health check para usar el dominio de Traefik:

# Antes (fallaba)
curl http://localhost:3000/health

# Despues (funciona)
curl https://test.monghit.com/health

4. Rollback No Cambiaba la Version

Problema: Despues de un rollback, el siguiente deploy restauraba la version anterior.

Causa: git pull no sobrescribe cambios locales en docker-compose.yml.

Solucion: Agregar reset del archivo antes del pull:

git checkout -- docker-compose.yml
git pull

5. Imagenes Versionadas No Se Creaban

Problema: Las imagenes con tag de version (:1.0.5) no existian en ghcr.io.

Causa: El tag de Git se creaba en el mismo workflow, pero GitHub no re-dispara el workflow para evitar loops.

Solucion: Crear los tags de imagen directamente en el build:

tags: |
  ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:main
  ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.pkg_version.outputs.version }}
  ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

6. Rollback Fallaba en Imagenes Privadas

Problema: docker compose pull fallaba con "denied" al intentar descargar la imagen.

Causa: El workflow de rollback no hacia login a ghcr.io.

Solucion: Agregar login antes del pull:

echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
docker compose pull

7. Verificacion de Version Fallaba en Versiones Antiguas

Problema: El rollback a v1.0.0 fallaba la verificacion aunque el contenedor corria bien.

Causa: La v1.0.0 no tenia el campo version en el endpoint /health.

Solucion: Aceptar respuestas sin campo version:

if [ -z "$DEPLOYED_VERSION" ]; then
  echo "Version antigua sin info de version en /health"
  echo "Health check OK"
  exit 0
fi

8. Docker Compose Status Check Fallaba

Problema: docker compose ps | grep -q "running" fallaba aunque el contenedor estaba corriendo.

Causa: El formato de salida de docker compose ps cambio en versiones recientes.

Solucion: Confiar en el health check en lugar del grep:

# Antes (no confiable)
if ! docker compose ps | grep -q "running"; then

# Despues (confiable)
docker compose ps  # Solo informativo
# Confiar en el health check HTTP

Estructura del Proyecto

test-deploy/
├── .github/
│   └── workflows/
│       ├── deploy.yml           # Deploy automatico en push a main
│       ├── rollback.yml         # Rollback manual a version especifica
│       └── validate-version.yml # Validacion y auto-bump de version en PRs
├── .dockerignore                # Excluir node_modules y .git
├── Dockerfile                   # Imagen Node.js Alpine con usuario no-root
├── docker-compose.yml           # Configuracion con labels de Traefik
├── index.js                     # Servidor Express con Actuator y docs
├── package.json                 # Metadata y version de la app
├── CONTRIBUTING.md              # Guia de contribucion con GitFlow
└── README.md

Endpoints

Documentacion (raiz)

La aplicacion sirve documentacion markdown renderizada como HTML con soporte para diagramas Mermaid:

Los diagramas Mermaid se renderizan automaticamente usando Mermaid.js.

Infografias

Versiones visuales e interactivas de la documentacion:

Health Check

Actuator Endpoints

Endpoints estilo Spring Boot Actuator para monitoreo y diagnostico:

/actuator/health

{
  "status": "UP",
  "components": {
    "diskSpace": { "status": "UP", "details": { "total": "31 GB", "free": "23 GB" } },
    "memory": { "status": "UP", "details": { "used": "23%", "heap": "8 MB" } },
    "process": { "status": "UP", "details": { "uptime": "5s", "pid": 1234 } }
  }
}

/actuator/info

{
  "app": { "name": "test-deploy", "version": "1.1.6" },
  "git": {
    "commit": { "hash": "abc123...", "message": "feat: ...", "author": {...} },
    "branch": "main"
  },
  "build": { "time": "2026-01-16T...", "nodeVersion": "v24.x.x" }
}

/actuator/metrics

{
  "measurements": {
    "process.uptime": { "value": 123, "unit": "seconds" },
    "system.cpu.count": { "value": 12, "unit": "cores" },
    "system.cpu.load": { "value": [1.5, 1.2, 0.9], "unit": "average" },
    "process.memory.heap.used": { "value": 8748160, "formatted": "8.34 MB" },
    "system.memory.total": { "formatted": "31.04 GB" },
    "system.memory.free": { "formatted": "23.64 GB" }
  }
}

/actuator/env

Variables de entorno con valores sensibles (password, token, key, secret, auth, etc.) filtrados automaticamente como ******.

CI/CD Centralizado

Este proyecto utiliza workflows reutilizables centralizados en el repositorio monghit-server/.github. Esto permite:

• Mantener la logica de CI/CD en un solo lugar
• Actualizar todos los proyectos de la organizacion con un solo cambio
• Reducir duplicacion de codigo (de ~380 lineas a ~80 lineas)
• Estandarizar pipelines entre proyectos

Arquitectura CI/CD

Workflows Reutilizables

Actions Reutilizables

Uso en este proyecto

deploy.yml (68 lineas vs 188 originales):

jobs:
  build:
    uses: monghit-server/.github/.github/workflows/docker-build.yml@main

  deploy:
    uses: monghit-server/.github/.github/workflows/deploy.yml@main
    with:
      app_name: test-deploy
      health_url: https://test.monghit.com/health

validate-version.yml (12 lineas vs 102 originales):

jobs:
  validate:
    uses: monghit-server/.github/.github/workflows/validate-pr.yml@main

Agregar CI/CD a un nuevo proyecto

1. Crear .github/workflows/ci.yml:

name: CI/CD

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

jobs:
  validate:
    if: github.event_name == 'pull_request'
    uses: monghit-server/.github/.github/workflows/validate-pr.yml@main

  build:
    if: github.event_name == 'push'
    permissions:
      contents: read
      packages: write
    uses: monghit-server/.github/.github/workflows/docker-build.yml@main

  deploy:
    if: github.event_name == 'push'
    needs: build
    uses: monghit-server/.github/.github/workflows/deploy.yml@main
    with:
      app_name: mi-app
      app_path: /opt/apps/mi-app
      health_url: https://mi-app.monghit.com/health
    secrets:
      SERVER_HOST: ${{ secrets.SERVER_HOST }}
      SERVER_USER: ${{ secrets.SERVER_USER }}
      SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

2. Configurar secrets a nivel de organizacion o repositorio.

Workflows Locales

Deploy (deploy.yml)

Se ejecuta en push a main:

1. create-tag: Crea tag automatico basado en package.json
2. build: Usa workflow centralizado para build Docker
3. deploy: Usa workflow centralizado para deploy SSH

Rollback (rollback.yml)

Se ejecuta manualmente desde GitHub Actions:

1. Seleccionar version a desplegar (o dejar vacio para ver disponibles)
2. Valida que el tag exista
3. Cambia imagen en el servidor
4. Verifica health check

Validate Version (validate-version.yml)

Se ejecuta en PRs a main usando el workflow centralizado:

1. check-version: Valida que la version sea diferente y el tag no exista
2. auto-bump: Incrementa version automaticamente si es igual a main
3. security-audit: Ejecuta npm audit

Imagenes Docker

Cada build crea tres tags en ghcr.io:

Gestion de Imagenes

Las imagenes se almacenan en ghcr.io y se descargan al servidor en cada deploy.

Tags de version en el servidor: El deploy actualiza automaticamente el docker-compose.yml del servidor para usar el tag de version especifico (ej: :1.1.5). Esto tiene dos ventajas:

• Evita acumular imagenes sin tag (dangling) que ocupan espacio
• Permite saber exactamente que version esta corriendo en el servidor

Limpieza manual (si es necesario):

# Eliminar imagenes sin tag (dangling)
docker image prune -f

# Ver imagenes actuales
docker images

Las capas base de Docker son compartidas entre versiones, por lo que el espacio real utilizado es menor al mostrado.

Seguridad

Como usar

Deploy nueva version

# 1. Actualizar version en package.json
# 2. Commit y push
git add -A
git commit -m "Bump version to X.X.X"
git push origin main

Rollback

1. Ir a Actions > Rollback
2. Click "Run workflow"
3. Ingresar version (ej: 1.0.8) o dejar vacio para ver disponibles
4. Click "Run workflow"

Ver versiones disponibles

• GitHub Packages

Notificaciones

Las notificaciones se envian a un webhook de n8n que las redirige a Telegram. Se activan cuando falla cualquier paso de los workflows.

Composite Action Centralizada

Las notificaciones estan centralizadas en una Composite Action reutilizable ubicada en el repositorio central monghit-server/.github/actions/notify-telegram/. Esto permite:

• Mantener la logica de notificacion en un solo lugar para toda la organizacion
• Reutilizar el mismo codigo en todos los proyectos
• Facilitar cambios futuros (solo se modifica un archivo en el repo central)

Uso en workflows:

- name: Notify Telegram on failure
  if: failure()
  uses: monghit-server/.github/actions/notify-telegram@main
  with:
    webhook_url: ${{ secrets.N8N_WEBHOOK_TO_TELEGRAM_URL }}
    event: deploy_failed
    repository: ${{ github.repository }}
    actor: ${{ github.actor }}
    run_url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

Eventos

Formato del webhook

{
  "event": "deploy_failed",
  "repository": "user/repo",
  "branch": "main",
  "commit": "abc123...",
  "version": "1.0.0",
  "actor": "username",
  "run_url": "https://github.com/user/repo/actions/runs/123"
}

Configuracion

Secrets requeridos

Como configurar secrets en GitHub

1. Ir al repositorio en GitHub
2. Click en Settings (pestaña superior)
3. En el menu lateral, ir a Secrets and variables > Actions
4. Click en New repository secret
5. Ingresar el nombre del secret (ej: SERVER_HOST) y su valor
6. Click en Add secret

Ejemplo para SSH_PRIVATE_KEY:

# Copiar el contenido de la llave privada
cat ~/.ssh/id_ed25519

Pegar el contenido completo incluyendo -----BEGIN OPENSSH PRIVATE KEY----- y -----END OPENSSH PRIVATE KEY-----.

Ejemplo para N8N_WEBHOOK_TO_TELEGRAM_URL:

https://tu-instancia-n8n.com/webhook/xxx-xxx-xxx

Esta URL se obtiene del nodo Webhook en tu workflow de n8n que envia mensajes a Telegram.

Proteccion de rama

Configurar en Settings > Branches > main:

• Require pull request before merging
• Require status checks: check-version, security-audit
• Do not allow bypassing the above settings

Configuracion Git local (opcional)

Para usar diferentes usuarios de Git por carpeta:

# ~/.gitconfig
[includeIf "gitdir:~/Git/personal/monghithub/"]
    path = ~/.gitconfig-monghit

# ~/.gitconfig-monghit
[user]
    name = usuario
    email = email@example.com
[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519_github2 -o IdentitiesOnly=yes

Tecnologias

Infografias

Disponibles versiones visuales e interactivas de la documentacion:

• Indice de infografias
• Infografia: Test Deploy
• Infografia: Guia de Contribucion

Infografia

Ver la version visual de este documento para un resumen interactivo.

Licencia

MIT