Pipeline CI del backend (GitHub Actions)¶

Pipeline que construye la imagen del backend y la publica en GHCR automáticamente.

Archivo¶

Triggers¶

Evento	Resultado	Tags publicados
`git push origin main`	build automático	`:staging` + `:staging-<sha>`
`git tag v1.2.3 && git push --tags`	build de release	`:production` + `:production-<sha>`
Manual desde UI ("Run workflow")	elige el ambiente	el que se haya elegido

Estrategia trunk-based con tags: el día a día va a staging por mergear a main. Producción requiere acción deliberada (crear el tag).

Imagen publicada¶

ghcr.io/compulandiati/oms-backend:<tag>

Cada build genera dos tags: - Móvil (:staging o :production) — siempre apunta al último build - Inmutable (:staging-<sha> o :production-<sha>) — para rollback

Permisos¶

El workflow usa el GITHUB_TOKEN automático con: - contents: read — para checkout - packages: write — para pushear a GHCR

No requiere PAT propio. Pero: si el package en GHCR fue creado manualmente antes del primer run del CI, hay que linkearlo al repo en Settings → Manage Actions access para que el workflow pueda escribirlo.

Particularidades¶

1. Normalización del owner a minúscula¶

GHCR rechaza paths con mayúsculas (CompulandiaTI → falla). El step "Normalizar owner" hace ${var,,} (bash) para convertir a compulandiati. Sin este paso, falla con 400 Bad Request.

2. Cache de GitHub Actions (`type=gha`)¶

Los builds sucesivos reutilizan capas cacheadas. Primer build: ~3 minutos. Builds posteriores sin cambios en package-lock.json: ~30 segundos.

3. Resolución del ambiente¶

El nombre del ambiente (staging/production) se resuelve en runtime según el trigger: - workflow_dispatch → input del usuario - tag v* → production - otro caso → staging

Esa decisión vive en el step "Resolver ambiente". Si querés cambiar la estrategia (ej: rama develop → staging, main → production), se ajusta ahí.

Cuándo se actualiza el workflow¶

Cambiar la imagen base de Docker → no toca el workflow
Cambiar variables runtime del backend → no toca el workflow
Agregar tests automáticos antes del build → sí, agregar un step npm test antes de "Build y push"
Cambiar la convención de tags → sí, ajustar el step "Resolver ambiente"

Operación¶

Ver el estado de los runs¶

https://github.com/CompulandiaTI/<repo-backend>/actions

Volver a correr un workflow fallido¶

UI → workflow run → "Re-run jobs" (top right). Útil cuando el fallo fue transitorio (red, runner caído).

Pushear a producción¶

# En main, después de validar staging
git tag v1.2.3
git push origin v1.2.3

GitHub Actions detecta el tag y construye con :production. El servidor de producción puede entonces hacer docker compose pull && up -d.

Rollback rápido¶

Si el último build a producción rompió algo: 1. Identificar el sha del último build estable en GHCR 2. En el servidor, editar deployment/.env: BACKEND_TAG=production-<sha-estable> 3. docker compose pull && docker compose up -d

Limpieza pendiente¶

El workflow actual tiene hquintero-dev como rama de prueba (línea 23). Cuando se valide en staging real, remover esa línea para que solo main y tags v* triggereen builds.