GitLab Workflow

Resumen Ejecutivo

Este documento define el modelo de colaboración técnica en HERA, diseñado para maximizar la velocidad de entrega sin comprometer la estabilidad de producción.

• Flujo Estandarizado: Implementa un modelo híbrido entre GitFlow y Trunk-based que asegura una integración continua en develop y despliegues controlados en main.
• Gobernanza mediante MRs: Establece los Merge Requests (MR) como el único mecanismo de promoción de código, garantizando la trazabilidad, la revisión por pares y el cumplimiento de Quality Gates.
• Agilidad Operativa: Define procesos expeditos para correcciones urgentes (hotfixes) y criterios claros para la evolución hacia modelos de despliegue continuo (Trunk-based puro).

El GitLab Workflow define cómo los equipos de desarrollo colaboran usando Git y GitLab. Este modelo estandariza el flujo de trabajo desde la creación de código hasta el despliegue en producción, asegurando calidad, trazabilidad y colaboración efectiva.

Estándares complementarios

Este workflow se apoya en dos estándares mandatorios que todo MR debe respetar:

• Estructura de Repositorios — taxonomía Product-Centric de 5 niveles
• Estándares de Configuración — variables de entorno, secretos en GCP Secret Manager, External Secrets CRD. Validar el checklist R1–R12 en code review.

---

Modelo de Ramas (Branching Model)

Para mantener el orden y la calidad, todos los proyectos en HERA deben seguir una estrategia de ramas estandarizada, con dos ramas principales protegidas y ramas de feature de corta duración.

Estrategia de Ramas HERA

main

MR + Aprobación Tech Lead + QA

→ Producción (PRD)

develop

MR feature

MR fix

→ Auto-deploy DEV & QA

feature/
task-A

Merge Request hacia develop

fix/
bug-B

Merge Request hacia develop

main — Protegida · Solo Producción

develop — Integración continua

feature/* — Corta duración

fix/* — Corrección de bugs

Mensaje clave Dos ramas protegidas: develop para integración, main para producción. Todo cambio entra por Merge Request.

Ramas Principales

• main: Esta rama es sagrada. Refleja el estado actual de Producción.
  • Nadie puede hacer push directo. Los cambios solo llegan a través de Merge Requests desde develop.
  • Cada merge a main es, en efecto, una release a producción.
• develop: Es la rama principal de integración.
  • Representa la última versión del código con todas las nuevas funcionalidades listas.
  • Se despliega automáticamente a los ambientes de DEV y QA.
  • Todas las ramas de trabajo (feature, fix, etc.) se crean a partir de develop.

Reglas Obligatorias

1. La rama main está protegida. No se permite el push directo.
2. Toda nueva feature o fix debe crearse en una rama separada a partir de develop.
3. Usa la convención de nombres tipo/descripcion-corta (ej. feature/login-oauth).
4. Mantén las ramas de feature pequeñas y de corta duración para facilitar la revisión y el merge.

Las feature branches NO son cuello de botella

Las ramas de trabajo (feature/*, fix/*, chore/*, spike/*) no están protegidas. Cualquier persona con rol Developer puede crearlas, pushear a ellas y abrir un MR sin intervención del equipo DevOps Operacional. La protección aplica únicamente a develop y main — por eso el flujo diario del dev no depende de DevOps para avanzar.

---

Flujo de Desarrollo (Day Two)

Este es el ciclo de trabajo diario para cualquier desarrollador en HERA.

1. Sincroniza y Crea tu Rama: Asegúrate de tener la última versión de develop y crea tu nueva rama de trabajo.

   git checkout develop
   git pull origin develop
   git checkout -b feature/nueva-funcionalidad

2. Desarrolla y Haz Commits: Realiza tu trabajo, haciendo commits pequeños y frecuentes con mensajes claros (ver Conventional Commits).

   git add .
   git commit -m "feat(auth): add login form component"

3. Sube tus Cambios y Crea el Merge Request (MR): Una vez que tu trabajo esté listo para ser integrado, súbelo y crea un MR en GitLab.

   git push -u origin feature/nueva-funcionalidad
   # Ahora, ve a GitLab y crea el Merge Request de 'feature/...' hacia 'develop'

4. Revisión de Código y Merge a develop:

   • Tu Tech Lead o un compañero revisará tu código directamente en el MR.
   • Una vez aprobado y el pipeline de CI pase exitosamente, se hace “Merge”.
   • Resultado: Al hacer merge, el pipeline despliega automáticamente al ambiente de DEV.

---

Flujo de Promoción: DEV → QA → PRD

La promoción de código sigue un flujo controlado con responsabilidades claras entre el equipo de desarrollo y el equipo de DevOps Operacional. Un solo Merge Request genera el commit que se despliega a QA y luego a PRD — no se crean MRs adicionales.

Paso 1 — Developer crea el MR de develop → main

El Developer (o Tech Lead) es quien crea el Merge Request porque conoce qué funcionalidades están listas para pasar al ambiente de QA. El Developer sabe qué features se completaron, qué bugs se corrigieron y qué está estable en DEV.

El MR debe incluir:

• Título con Conventional Commits: feat(checkout): implement payment gateway integration
• Descripción con las funcionalidades incluidas y los criterios de validación para QA
• Checklist de lo que negocio debe validar en QA

El Developer crea el MR pero no puede integrarlo

Los Developers tienen rol Developer en GitLab. Pueden crear MRs a main pero no tienen permiso para integrarlos — la branch main está protegida y solo permite merge por Maintainers (DevOps Operacionales).

Paso 2 — DevOps Operacional revisa e integra

El DevOps Operacional (rol Maintainer) revisa el MR:

• Verifica que el pipeline de CI pasó todos los Quality Gates
• Confirma que no hay vulnerabilidades Critical/High sin resolver
• Valida que la descripción del MR está completa
• Aprueba y ejecuta el merge a main

Al integrar el MR, se genera un commit en main que es la versión candidata para QA y PRD.

Paso 3 — Deploy manual a QA

Después del merge, el pipeline de main muestra el job deploy-qa como manual (botón play). El DevOps Operacional lo ejecuta cuando el ambiente de QA está disponible.

• El deploy usa exactamente el mismo commit que se generó del MR
• No se crea ningún MR adicional para QA
• El equipo de QA y negocio validan las funcionalidades en este ambiente

Paso 4 — Validación de negocio en QA

El equipo de negocio (Product Owner) valida en QA que:

• Las funcionalidades cumplen con los criterios de aceptación
• No hay regresiones en funcionalidad existente
• La experiencia de usuario es correcta

Esta validación no ocurre en GitLab — ocurre en el ambiente de QA. El PO comunica su aprobación al equipo de DevOps.

Paso 5 — Deploy manual a PRD

Con la aprobación de negocio, el DevOps Operacional ejecuta el job deploy-prd en el mismo pipeline de main — es el mismo commit que pasó por QA. No se hace ningún merge adicional.

Concepto	Detalle
Mismo commit	El código que se desplegó en QA es bit-identical al que se despliega en PRD
Sin MR adicional	No se crea un nuevo MR para PRD — se usa el pipeline del merge original
Ventana de deploy	Lunes a jueves 9:00-16:00 CST. Viernes antes de 14:00. Fines de semana solo emergencias
Rollback disponible	Si algo falla en PRD: kubectl rollout undo en menos de 5 minutos

Un solo commit viaja de QA a PRD

El commit que se validó en QA es exactamente el mismo que se despliega en PRD. No se reconstruye la imagen, no se recompila el código, no se crea otro MR. Esto es el principio Build Once, Deploy Many — si funciona en QA, funciona en PRD porque es el mismo artefacto.

Resumen visual del flujo completo

Paso	Quién	Acción	Resultado
1	Developer	Crea MR de develop → main con descripción de features	MR abierto, pendiente de revisión
2	DevOps Operacional	Revisa, aprueba e integra el MR	Commit en main, pipeline habilitado
3	DevOps Operacional	Ejecuta deploy manual a QA	Versión corriendo en QA
4	Product Owner / Negocio	Valida funcionalidades en QA y da el OK	Aprobación para PRD
5	DevOps Operacional	Ejecuta deploy manual a PRD (mismo commit)	Versión en producción

Buenas prácticas para Merge Requests

• Título descriptivo: Usa Conventional Commits (feat(auth): implement OAuth login)
• Descripción completa: Explica el “qué” y el “por qué”. Lista las features incluidas y qué debe validar QA
• MRs pequeños: Un MR debe enfocarse en un conjunto cohesivo de cambios. Menos de 400 líneas de cambio es ideal
• No mezclar: No combines features, fixes y refactors en el mismo MR

---

Modelo CI/CD: Branches, Roles y Ambientes

Este es el modelo operativo que conecta las ramas con los ambientes de despliegue. Define quién puede hacer qué y cómo fluye un cambio desde el código hasta producción.

Flujo completo

1. El Developer crea una feature branch desde develop y desarrolla su cambio.
2. El Developer abre un MR hacia develop. Otro Developer lo revisa, aprueba e integra.
3. El pipeline de CI ejecuta automáticamente el Deploy a DEV al integrar el MR.
4. Validado DEV, el Developer (o Tech Lead) crea un MR de develop hacia main. No puede integrarlo — solo tiene permisos de creación.
5. El DevOps Operacional (Maintainer) revisa el MR, aprueba e integra.
6. El pipeline de CD habilita el Deploy manual a QA, que el DevOps Operacional ejecuta.
7. Validado QA por el equipo de negocio y con aprobación explícita, el DevOps Operacional ejecuta el Deploy manual a PRD sobre el mismo commit.

Principio Build Once, Deploy Many

El commit que pasa por QA es bit-identical al que se despliega en PRD. No se reconstruye la imagen ni se recompila el código entre ambientes. Si el artefacto funciona en QA, funciona en PRD — porque es el mismo artefacto.

Ambientes y triggers

Ambiente	Branch	Trigger	Quién ejecuta	Condición previa
DEV	develop	Automático al merge	Pipeline (sin intervención)	MR aprobado entre developers
QA	main	Manual	DevOps Operacional	MR aprobado e integrado por DevOps
PRD	main	Manual	DevOps Operacional	QA validado + aprobación de negocio

Roles y permisos por branch

Rol	Rol GitLab	Puede integrar a develop	Puede integrar a main	Puede ejecutar deploy QA/PRD
Developer	Developer	Sí	No (solo crea el MR)	No
Tech Lead	Developer	Sí	No (solo crea el MR)	No
QA Engineer	Developer	Sí	No	No
DevOps Operacional	Maintainer	Sí	Sí (aprueba e integra)	Sí
Líder DevOps	Maintainer	Sí	Sí	Sí

Configuración de branches protegidas en GitLab

Branch develop (CI → DEV)

Campo	Valor
Allowed to merge	Developers + Maintainers
Allowed to push and merge	No one
Allowed to force push	Desactivado

Los developers se autogestionan: crean MRs, revisan entre ellos e integran los cambios aprobados. El pipeline despliega a DEV automáticamente.

Branch main (CD → QA → PRD)

Campo	Valor
Allowed to merge	Maintainers (solo DevOps Operacionales)
Allowed to push and merge	No one
Allowed to force push	Desactivado

Los developers crean el MR a main pero no pueden integrarlo. Solo los DevOps Operacionales (Maintainer) aprueban, integran y ejecutan el deploy manual a QA. Si QA es exitoso y negocio aprueba, ejecutan el deploy a PRD.

Protected Environments — control del deploy

Las Protected Environments son una capa de control independiente de las Protected Branches. Una persona con rol Maintainer que puede mergear a main no necesariamente puede deployar a PRD — el acceso al ambiente se configura por separado.

Ruta en GitLab: Settings → CI/CD → Protected environments

Environment	Allowed to deploy	Propósito
development	Developer + Maintainer	Cualquier dev puede deployar al ambiente de pruebas al mergear a develop
qa	Maintainer	Solo DevOps Operacional ejecuta el deploy manual a QA
production	Maintainer	Solo DevOps Operacional ejecuta el deploy manual a PRD

Por qué Protected Environments es obligatorio

Sin Protected Environments, cualquier pipeline que corra sobre main permitiría ejecutar deploy-prd a cualquier desarrollador con visibilidad del proyecto. Al proteger el ambiente production, se garantiza que solo el rol Maintainer puede hacer click en el job manual — es el control efectivo que mantiene a DevOps Operacional como único responsable del deploy productivo.

El nombre del environment en el .gitlab-ci.yml debe coincidir exactamente con el nombre configurado aquí (ver environment: production en el pipeline más abajo).

Controles de revisión y calidad en MR

Complementan a las Protected Branches y Protected Environments imponiendo validaciones técnicas antes del merge y facilitando que los reviewers correctos se asignen automáticamente.

Ruta en GitLab: Settings → Merge requests

Control	Valor recomendado	Efecto
Merge checks → Pipelines must succeed	ON	Bloquea el merge si el pipeline CI no está en verde
Merge checks → All threads must be resolved	ON	Bloquea el merge si hay discusiones abiertas en el código
Merge method → Merge commit	Según convención del equipo	Historial trazable del merge en main y develop
Squash commits when merging → Encourage	Encourage	Historial más limpio en ramas protegidas

Convención del equipo: 2 aprobaciones para MRs a main

Los MRs de develop → main requieren 2 aprobaciones humanas por convención del equipo:

1. Tech Lead del equipo — valida que las funcionalidades están listas, cubiertas por tests y sin regresiones conocidas.
2. DevOps Operacional — valida Quality Gates, pipeline CI en verde y descripción completa del MR.

Cómo se cumple en la práctica:

• CODEOWNERS asigna automáticamente al Tech Lead como reviewer al abrir el MR (ver sección siguiente).
• El DevOps Operacional (único Maintainer que puede hacer el merge a main, por Protected Branches) verifica la presencia de ambas aprobaciones antes de integrar. Es el punto de control efectivo del flujo.
• Ambas aprobaciones quedan trazadas en el MR como evidencia de gobierno ante auditoría.

El cierre del gobierno está en quién puede mergear (Protected Branches) y quién puede deployar (Protected Environments), no en reglas automáticas de aprobación.

CODEOWNERS — asignación automática de revisores

El archivo .gitlab/CODEOWNERS declara quién es dueño de cada path del repositorio. Al abrir un MR, GitLab sugiere automáticamente como reviewers a los owners de los archivos modificados — evita que el autor tenga que recordar a quién asignar.

Ubicación: .gitlab/CODEOWNERS en la raíz del repositorio.

# Todo cambio requiere revisión del Tech Lead del equipo
*                 @tech-lead-username

# Paths sensibles: Tech Lead + Security
/src/payments/    @tech-lead-username @security-lead-username
/src/auth/        @tech-lead-username @security-lead-username

# Pipeline CI/CD: DevOps Operacional
/.gitlab-ci.yml   @devops-ops-lead-username

# Manifiestos Helm/K8s: Platform Engineering
/helm/            @platform-eng-lead-username
/k8s/             @platform-eng-lead-username

CODEOWNERS como disciplina de equipo

CODEOWNERS asigna automáticamente a los reviewers correctos al abrir el MR. La convención del equipo es que un MR no se mergea sin la aprobación del owner listado. La regla de Minimum approvals complementa este control: fuerza un número mínimo de votos, y CODEOWNERS dirige esos votos a las personas correctas.

Jobs de deploy — heredados del Golden Pipeline

Los jobs deploy-dev, deploy-qa y deploy-prd no se definen en el .gitlab-ci.yml del proyecto. Se heredan del Golden Pipeline a través de la directiva include: al inicio del pipeline del repo — el equipo de producto no escribe el YAML de deploy a mano.

Ubicación canónica del template: grupo-herdez/platform/pipelines/gitlab-ci/

Contrato de los jobs de deploy (definido en el template)

Job	environment:	rules / trigger	Branch objetivo	Quién ejecuta
deploy-dev	development	Automático al merge a develop	develop	Pipeline (sin intervención humana)
deploy-qa	qa	Manual (when: manual) sobre main	main	DevOps Operacional (Maintainer + acceso al Protected Environment qa)
deploy-prd	production	Manual (when: manual + needs: [deploy-qa]) sobre main	main	DevOps Operacional (Maintainer + acceso al Protected Environment production)

El valor de environment: en cada job debe coincidir exactamente con el nombre del Protected Environment configurado en los pasos 4, 5 y 6 del checklist inicial. El pipeline del proyecto no redefine estos jobs ni sobrescribe su script: — simplemente los hereda del template.

Por qué el portal no publica el YAML de estos jobs

La implementación concreta del pipeline de deploy vive en el Golden Pipeline. Duplicarla aquí generaría drift: cualquier evolución del template (nuevas stages, cambios de trigger, nuevos needs) no se reflejaría en el portal hasta que alguien recordara actualizarlo — y cualquier divergencia silenciosa haría que esta página mintiera.

El portal documenta el contrato observable (ambientes, triggers, responsables); la implementación es responsabilidad del repo del template, y es la única fuente de verdad. Para ver la versión actual del pipeline, consulta directamente el repo.

El Developer nunca toca QA ni PRD

Un developer puede hacer tantos deploys a DEV como necesite — es su ambiente de pruebas. Pero para QA y PRD, el proceso pasa por DevOps Operacional. Esto garantiza que lo que llega a producción fue revisado, aprobado y desplegado por el equipo responsable de la estabilidad de la plataforma.

¿Por qué QA es manual y no automático?

Porque el deploy a QA implica que el equipo de QA va a validar funcionalidad, rendimiento e integración. Si fuera automático, cada merge a main dispararía un deploy que podría interrumpir las pruebas en curso. El trigger manual permite al equipo de DevOps coordinar el momento adecuado.

---

Paso a paso de configuración inicial del repo

Al crear un repositorio nuevo bajo grupo-herdez/products/..., el equipo DevOps Operacional aplica esta configuración antes del primer MR. Garantiza gobierno desde el día 1 y evita tener que “cerrar huecos” después de que el repo ya tiene actividad.

Checklist de 10 pasos

#	Paso	Ruta en GitLab	Detalle
1	Invitar miembros con su rol	Project → Members → Invite members	Developers (devs + TL + QA) · Maintainers (DevOps Operacional) · Owner (admin plataforma HERA). Ver tabla de roles.
2	Proteger develop	Settings → Repository → Protected branches	Allowed to merge: Developers + Maintainers · Allowed to push and merge: No one · Allowed to force push: OFF
3	Proteger main	Settings → Repository → Protected branches	Allowed to merge: Maintainers · Allowed to push and merge: No one · Allowed to force push: OFF
4	Proteger environment development	Settings → CI/CD → Protected environments	Allowed to deploy: Developer + Maintainer
5	Proteger environment qa	Settings → CI/CD → Protected environments	Allowed to deploy: Maintainer
6	Proteger environment production	Settings → CI/CD → Protected environments	Allowed to deploy: Maintainer
7	Configurar controles de MR	Settings → Merge requests	Merge checks → Pipelines must succeed: ON · Merge checks → All threads must be resolved: ON · Merge method: Merge commit · Squash commits: Encourage. La convención de equipo “2 aprobaciones para MRs a main” se enforce vía CODEOWNERS + verificación del DevOps Operacional antes del merge.
8	Crear .gitlab/CODEOWNERS	Commit en rama inicial	Declarar owners por path (Tech Lead, Security, DevOps Ops, Platform). Ver ejemplo arriba.
9	Validar environment: en .gitlab-ci.yml	Revisar el pipeline del stack	deploy-qa debe referenciar environment: qa · deploy-prd debe referenciar environment: production. Los nombres deben coincidir exactamente con los Protected Environments de los pasos 5 y 6.
10	Validación final con MR dummy	Crear MR de prueba	Confirmar que: (a) un Developer no puede mergear a main · (b) el deploy a QA/PRD exige rol Maintainer · (c) el autor no puede auto-aprobar su propio MR

Resultado de aplicar el checklist

Garantía	Mecanismo que la hace cumplir
Developers crean feature branches sin pedir permiso	Ramas feature/* no protegidas (Paso 2)
Nadie pushea directo a develop ni a main	Allowed to push: No one en ambas (Pasos 2 y 3)
Solo DevOps Operacional mergea a main	Allowed to merge: Maintainers (Paso 3)
Solo DevOps Operacional deploya a QA y PRD	Protected Environments (Pasos 5 y 6)
Ningún MR se mergea sin revisión	Merge checks + asignación de reviewers vía CODEOWNERS + verificación del DevOps Operacional antes del merge (Pasos 7 y 8)
Los reviewers correctos se asignan automáticamente	CODEOWNERS (Paso 8)
El Tech Lead tiene autoridad de aprobación pero NO de merge ni deploy	Rol Developer + CODEOWNERS (Pasos 1 y 8)
Ninguna feature branch puede saltarse el pipeline CI	Quality Gates obligatorios antes de mergear

10 minutos de configuración, años de gobierno

Este checklist toma aproximadamente 10 minutos por repositorio. Saltárselo significa aceptar los defaults de GitLab: sin Protected Environments (cualquier Maintainer deploya a PRD), sin merge checks (MR se mergea con pipeline rojo o threads abiertos), sin CODEOWNERS (reviewers asignados a mano o se olvidan). El costo de no aplicarlo es fragmentación del gobierno y riesgo operacional reversible sólo con esfuerzo mucho mayor.

---

Comparativa: GitFlow vs Trunk-based vs Modelo HERA

El modelo HERA no nació en el vacío. Es una decisión deliberada posicionada entre los dos extremos del spectrum: GitFlow (más estructurado) y Trunk-based development (más ágil). Esta sección explica el porqué y cuándo cada modelo es apropiado.

Tabla comparativa

Aspecto	GitFlow	Trunk-based	Modelo HERA
Ramas principales	master + develop + release branches	Solo main	main + develop
Feature branches	Sí, larga duración	Sí, corta duración (menos de 1 día)	Sí, corta duración (menos de 3 días)
Release branches	Sí, obligatorias	No	No
Hotfix branches	Sí, dedicadas	Directo en main	Directo a main con MR fast-track
Frecuencia de deploy	Mensual o trimestral	Múltiples veces al día	Diaria a semanal
Complejidad	Alta — muchas ramas	Baja — una rama	Media — dos ramas
Curva de aprendizaje	Alta	Baja	Media
Coordinación entre equipos	Por release branch	Continua via feature flags	Via develop como punto de integración
Adecuado para	Productos con releases planeadas (software empaquetado)	Equipos maduros con CI/CD avanzado y feature flags	Organizaciones en transición de tradicional a DevOps maduro
Correlación con DORA high-performers	Baja	Alta	Media-alta

El spectrum visualizado

El spectrum de branching

HERA

menos coordinacion mas velocidad

GitFlow

• Estructura formal
• Multiples branches
• Releases planeadas

Hibrido Pragmatico HERA

• main + develop
• Feature branches cortas
• Modelo de transicion

Trunk-based

• Agilidad maxima
• Solo main
• Trunk always releasable

Evolucion natural conforme madura el equipo

Mensaje clave HERA está entre GitFlow y Trunk-based. El objetivo es evolucionar hacia Trunk-based puro.

Por qué HERA eligió este modelo

HERA está en transición desde operaciones tradicionales hacia DevOps maduro. El modelo de branching refleja esa realidad:

Razón	Detalle
Trunk-based puro requiere madurez avanzada	Feature flags maduros, monitoring sofisticado, cultura de continuous deployment. Grupo Herdez aún no está ahí en todos los productos.
GitFlow puro es overhead innecesario	No necesitamos release branches mensuales. La industria moderna no opera así.
develop actúa como buffer de integración	Permite ejecutar pruebas en QA antes de PRD, sin la complejidad de release branches
MRs cortos compensan la rama develop	Si los MRs son menores a 3 días, el riesgo de divergencia es bajo
Familiar para equipos que vienen de GitFlow	La curva de aprendizaje es menor que ir directo a Trunk-based
Compatible con releases manuales a PRD	Cumple con políticas de aprobación + ventanas de deploy

HERA es un modelo de transición

El modelo HERA de branching no es el destino final — es un escalón. Conforme los productos maduran (más feature flags, mejor monitoring, automatización completa), el objetivo es evolucionar gradualmente hacia Trunk-based development puro para los productos que estén listos. Ver Cuándo evolucionar más abajo.

Cuándo NO usar el modelo HERA

Situación	Modelo recomendado
Software empaquetado con releases mensuales planeadas	GitFlow puro
Equipo maduro con feature flags + monitoring + CD	Trunk-based puro
Producto experimental sin tráfico real	Trunk-based simplificado
Sistema con regulaciones que requieren change windows estrictas	GitFlow con release branches

---

Hotfixes — Cómo se manejan

Un hotfix es un parche urgente a producción que NO puede esperar al ciclo normal develop → main. Casos típicos: vulnerabilidad crítica, bug bloqueante de negocio, regresión post-deploy.

Flujo de hotfix en HERA

Flujo de Hotfix en HERA

Parche urgente a produccion que NO espera al ciclo normal develop a main

1

main PRD actual: v1.2.3

git checkout -b hotfix/... origin/main

2

hotfix/security-patch-v1.2.4 Fix minimo, NO incluye otras features

MR fast-track a main

3

main PRD: v1.2.4 — Pipeline despliega con aprobacion expedita

Merge back a develop (obligatorio)

4

develop Incluye el hotfix para que el proximo release no lo revierta

Mensaje clave Branch desde main, fix, MR fast-track a main, merge-back obligatorio a develop en 24h.

Reglas obligatorias de hotfix

Regla	Por qué
Branch desde main, no desde develop	develop puede tener cambios no validados
Solo el fix mínimo	Cualquier “y de paso…” rompe el propósito del hotfix
MR directamente a main	No pasa por develop (eso lo demoraría)
Aprobación expedita	1 Tech Lead + Security Engineer (en vez de 3 aprobaciones normales)
Pipeline completo igual	Quality Gates NO se relajan ni siquiera en hotfix
Merge back a develop obligatorio	Sin esto, el siguiente release a develop → main revertiría el hotfix
Post-mortem dentro de 48 horas	Documentar qué falló, por qué urgió, cómo prevenir

Anti-pattern: hotfix sin merge back

main: v1.2.3 → hotfix → v1.2.4 (con fix de seguridad)
develop: v1.3.0 (sin el fix)

# Próximo release develop → main
develop → main: v1.3.0 → ¡REVIERTE EL HOTFIX! 💥

Solución: después de cada hotfix a main, hacer git merge main en develop o cherry-pick del commit del fix.

---

Sobre Release Branches

Esta es una decisión deliberada de HERA: NO se usan release branches.

Por qué NO

Razón
Agregan complejidad sin valor para el modelo de releases continuos de HERA
Requieren coordinación adicional entre equipos
Generan deuda de “qué cherry-pickeamos al release”
Modernamente, feature flags + Trunk-based reemplazan release branches
HERA usa el patrón “tag de release sobre main” en su lugar

Cuándo SÍ tendría sentido (excepciones)

• Software empaquetado distribuido a clientes (instalable, on-prem)
• Versiones LTS con backport de fixes (más de 1 año de soporte)
• Regulaciones que requieren freeze de código antes de release

Para HERA, ninguna de estas aplica hoy. Si en el futuro Grupo Herdez distribuye software on-premises, se reevaluará.

---

Cuándo evolucionar a Trunk-based puro

El modelo HERA es de transición. Trunk-based development puro es el destino para productos maduros. Estos son los criterios de readiness para que un producto pueda migrar:

Checklist de readiness

Criterio	Cumplido
✅ El producto tiene feature flags maduros (kill switches, gradual rollout)	[ ]
✅ Pipeline de CI corre en < 10 minutos consistentemente	[ ]
✅ Pipeline de CD permite deploy a PRD sin aprobación humana (automatizado con quality gates)	[ ]
✅ Cobertura de tests > 80% unit + integration	[ ]
✅ Tests E2E automatizados que corren post-deploy	[ ]
✅ Observabilidad madura: dashboards, SLOs, alertas con bajo umbral	[ ]
✅ Capacidad de rollback automático basado en métricas	[ ]
✅ Cultura de deploy múltiples veces al día ya establecida	[ ]
✅ El equipo ha leído y entiende los principios de Trunk-based	[ ]
✅ La organización acepta deploys a PRD sin gates manuales	[ ]

Si el producto cumple los 10 criterios, está listo para migrar a Trunk-based puro. La migración es voluntaria y se hace producto por producto, no big bang.

Cómo migrar (cuando esté listo)

1. Eliminar la rama develop — los feature branches se integran directamente a main
2. Habilitar deploy automático a PRD desde main (sin aprobación humana, con quality gates fuertes)
3. Reforzar feature flags — toda funcionalidad nueva detrás de un flag
4. Acortar feature branches a menos de 1 día (idealmente horas)
5. Tests E2E continuos post-deploy automático

Trunk-based no es para todos los productos

No todos los productos de Grupo Herdez deberían migrar a Trunk-based puro. Es ideal para productos con alto cambio + alta criticidad de delivery rápido (ej. e-commerce con experimentos constantes). Productos estables con cambios mensuales pueden quedarse en el modelo HERA cómodamente.

---

Resumen: Branching en HERA

Concepto	Estándar HERA
Modelo de branching	Híbrido — main + develop + feature branches cortas
Posicionamiento	Entre GitFlow y Trunk-based, más cerca de Trunk-based
Release branches	NO — usamos tags sobre main
Hotfixes	Branch desde main, MR fast-track, merge back obligatorio
Frecuencia objetivo	Diaria a semanal a PRD
Destino futuro	Trunk-based puro (producto por producto, cuando estén listos)
Razón del modelo actual	Pragmático para una organización en transición