Integración continua y releases

Actualización 2026-10-10: desarrollo es local, en el Kubernetes kubeadm de Docker Desktop, y GCP se usa solo para producción. Un merge a develop no aprovisiona ni despliega infraestructura en GCP. Luis Felipe Navarro Julio, único integrante del Grupo 17, actualiza su ambiente mediante la raíz Terraform environments/local; las imágenes se publican en Artifact Registry únicamente como parte de una release.

Principio

Backend, frontend web y móvil conservan versiones independientes. La versión de sport-app-platform representa una combinación compatible, probada y aceptada; no obliga a que todos los números de versión sean iguales.

flowchart LR
    HU[Push de una HU] --> CI[CI del componente]
    CI --> PR[PR a develop]
    PR --> DEV[Integración local]
    DEV --> C[Release del componente]
    C --> P[PR de plataforma]
    P --> ST[Integración local y validación de release]
    ST --> V[Versión de plataforma]
    V --> PROD[Promoción aprobada]

Flujo Git por repositorio

El flujo siguiente se aplica de manera independiente en sport-app-backend, sport-app-frontend, sport-app-movil y sport-app-platform. Cada repositorio conserva su historial, ramas, pull requests, CI y versión. Compartir el identificador HUxxx permite relacionar el trabajo, pero no mezcla los repositorios ni autoriza a publicar cambios de uno desde otro.

Responsabilidad de cada rama

Rama	Nace desde	Se integra en	Responsabilidad
main	releases y hotfix aprobados	no aplica	conservar el estado estable, liberable y etiquetado; no recibe desarrollo directo
develop	main al iniciar el flujo	release/*	integrar el siguiente sprint y recibir features y retornos de release/hotfix
feature/HUxxx-descripcion	develop	develop, mediante PR	implementar la parte de una HU que pertenece a ese repositorio
release/vX.Y.Z	develop	main y retorno a develop	congelar y estabilizar la versión; no acepta funcionalidades nuevas
hotfix/vX.Y.Z-descripcion	main o el tag vigente	main, develop y una release activa	corregir urgentemente una versión liberada y evitar que el defecto reaparezca

Flujo normal de una HU y una release

flowchart TB
    D["1. Actualizar develop"] --> F["2. Crear feature/HUxxx-descripcion"]
    F --> W["3. Implementar, probar y hacer push"]
    W --> CI["4. Ejecutar CI"]
    CI --> PRD["5. Abrir PR hacia develop"]
    PRD --> MD["6. Revisar y fusionar en develop"]
    MD --> R["7. Crear release/vX.Y.Z"]
    R --> E["8. Estabilizar y publicar componente"]
    E --> PP["9. Actualizar manifiesto y submódulo en plataforma"]
    PP --> PRM["10. PR de release hacia main"]
    PRM --> TAG["11. Crear tag y promover los mismos artefactos"]
    TAG --> RET["12. Retornar correcciones a develop"]

1. Se selecciona la HU en GitHub Projects, se determinan los repositorios afectados y se actualiza develop en cada uno.
2. En cada repositorio afectado se crea una rama propia feature/HUxxx-descripcion desde develop.
3. Cada rama implementa y prueba únicamente la responsabilidad de su componente; los commits conservan trazabilidad con la misma HU.
4. El push ejecuta la CI correspondiente y nunca fusiona automáticamente.
5. Cada feature abre su propio PR hacia develop.
6. El PR se revisa y se fusiona únicamente cuando los checks y criterios aplicables están aprobados.
7. Cuando el alcance del sprint está completo se crea release/vX.Y.Z en los repositorios que deban publicar versión.
8. La release se congela, se estabiliza y publica el artefacto del componente una sola vez; su digest o checksum queda inmutable.
9. sport-app-platform actualiza los punteros de submódulos y release-manifest.yaml con esas versiones exactas.
10. La release de plataforma abre su PR hacia main y ejecuta la validación integrada.
11. Después de aprobarla se crea el tag de plataforma y se promueven los mismos artefactos validados.
12. Toda corrección realizada durante la estabilización regresa mediante PR a develop.

Flujo de hotfix

flowchart TB
    I["1. Confirmar incidente y versión afectada"] --> H["2. Crear hotfix desde main o tag"]
    H --> T["3. Corregir y probar regresión"]
    T --> PM["4. PR hacia main"]
    PM --> PT["5. Publicar nuevo tag PATCH"]
    PT --> UP["6. Actualizar release de plataforma si cambia la composición"]
    UP --> RD["7. Retornar a develop y release activa"]

Un hotfix no nace desde develop. La corrección mínima se publica primero desde main, incrementa PATCH y después se retorna a develop y a cualquier release/* activa. Así la urgencia no elimina CI, revisión, trazabilidad ni sincronización.

Una HU distribuida entre repositorios

Por ejemplo, HU003 puede requerir tres ramas y tres PR independientes:

sport-app-backend:  feature/HU003-iniciar-sesion
sport-app-frontend: feature/HU003-iniciar-sesion
sport-app-movil:    feature/HU003-iniciar-sesion

La HU sigue siendo una sola en el backlog. Sus tareas técnicas se distribuyen por componente y la historia se considera aceptada únicamente cuando el incremento vertical requerido está integrado y verificado. La plataforma no desarrolla el código de esos componentes: fija sus releases compatibles y conserva la evidencia conjunta.

¿Qué ocurre con un push?

Evento	Resultado	¿Despliega?
Push a una rama feature/**, fix/** o chore/**	calidad y pruebas rápidas	No
PR hacia develop	validación completa, imagen candidata sin publicar y plan local seguro	No
Merge a develop	código integrado; el responsable reconstruye y aplica su ambiente local cuando lo necesite	No despliega GCP
PR de release de un componente	valida y publica su versión	No libera todo SportApp
PR de release de plataforma	contratos, integración, E2E y composición en local; staging no existe	No despliega producción
Versión de plataforma aprobada	promueve exactamente los artefactos probados	Producción con aprobación

Un push nunca realiza merge automático. main y develop deben estar protegidas.

¿Desde dónde se libera?

Alcance	Repositorio responsable
Imágenes y versión backend	sport-app-backend
Artefacto y versión web	sport-app-frontend
APK/AAB y versión móvil	sport-app-movil
Release completa de SportApp	sport-app-platform

La release completa comienza únicamente cuando cada componente modificado ya tiene un tag y un artefacto inmutable. La plataforma selecciona esas versiones, actualiza sus submódulos y crea un manifiesto con tags, commits y digests/checksums.

Release completa

sequenceDiagram
    participant B as Backend
    participant F as Frontend
    participant P as Plataforma
    participant S as Integración local
    participant R as Producción

    B-->>P: versión + imágenes por digest
    F-->>P: versión + artefacto por digest/checksum
    P->>P: validar tags, commits, submódulos y contratos
    P->>S: probar manifiesto candidato
    S-->>P: E2E, smoke y versiones observadas
    P->>P: aprobar y etiquetar versión de plataforma
    P->>R: promover los mismos artefactos

Nota — digest y checksum: un checksum es una huella digital del contenido, normalmente calculada con SHA-256. En una imagen OCI esa huella se expresa como un digest (@sha256:...). La versión o el tag identifica la release de forma legible, mientras que el digest/checksum permite comprobar que se promueven exactamente los mismos bytes que fueron validados y no un artefacto reconstruido o alterado.

La operación se lanzará desde Actions de sport-app-platform mediante el workflow prepare-platform-release.yml, cuando este sea implementado.

Versiones visibles y verificables

El despliegue debe poder mostrar y comprobar:

• versión y commit del frontend desde version.json;
• versión, commit y contrato del backend desde GET /version;
• versión de plataforma inyectada como configuración;
• digest realmente desplegado de cada imagen;
• compatibilidad entre contrato esperado y ofrecido.

Plataforma: v0.1.0
Frontend:   v0.1.0 · commit 89abcdef...
Backend:    v0.2.0 · commit 01234567...
Contrato:   v1.0.0 · compatible

Un smoke posterior compara estos valores con el manifiesto. Una diferencia bloquea la promoción o activa el rollback hacia una composición anterior.

Estado actual

Al 10 de octubre de 2026 el esquema de producción está documentado, pero todavía no está activo en GitHub Actions:

• el backend ya demostró su CI remota; el workflow anterior de entrega a development debe retirarse o convertirse en workflow de release sin despliegue automático;
• desarrollo se aplica localmente con Terraform y Docker Desktop, no desde un runner hacia GCP;
• móvil aún no tiene andamiaje ni pipeline;
• plataforma todavía no tiene workflows ni manifiesto ejecutable;
• producción GCP, Artifact Registry y OIDC/WIF continúan pendientes de aplicación y evidencia.

El manual operativo completo está en docs/esquema-ci-y-release.md.