--- title: 'Higiene de Git y monorrepositorios: commits atómicos, rebase y CI/CD de microservicios' description: 'Una guía completa sobre higiene de Git, commits atómicos, Conventional Commits, fusión frente a rebase, rebase interactivo, monorrepositorios frente a polirrepositorios y optimización de flujos de trabajo de CI/CD.' faq: - { question: '¿Cuál es el beneficio principal de los commits atómicos?', answer: "Los commits atómicos garantizan que cada commit contenga exactamente un cambio lógico y sus pruebas correspondientes. Esto facilita las revisiones de código, mantiene limpio el historial de commits, permite reversiones limpias de cambios específicos y hace que la depuración con herramientas como 'git bisect' sea sumamente eficiente." } - { question: '¿Cuándo debo usar merge y cuándo rebase?', answer: 'Use rebase en ramas locales y privadas para limpiar su historial, unificar commits de trabajo en progreso (WIP) y mantener un historial lineal antes de integrar. Use merge al combinar ramas de características completadas en ramas públicas compartidas (como main o develop) para preservar el orden cronológico real y evitar reescribir el historial compartido.' } - { question: '¿Cómo puedo evitar ejecutar pruebas para todos los servicios en un monorrepositorio al cambiar un solo servicio?', answer: "Puede optimizar su pipeline de CI utilizando filtrado basado en rutas (por ejemplo, el filtro 'paths' en GitHub Actions o 'rules:changes' en GitLab CI) de modo que un flujo de trabajo solo se active cuando se modifiquen archivos dentro del subdirectorio de un servicio específico." } published: '2026-06-15' --- # Higiene de Git y monorrepositorios: commits atómicos, rebase y CI/CD de microservicios Imagínese esto: es viernes por la tarde y hay un error crítico en producción. Revisa el historial de git para encontrar la regresión, pero todo lo que ve es una pared de commits: \"wip\", \"fix typo\", \"test\", \"hope this works\" y una red masiva y enredada de commits de fusión (merge). Encontrar el cambio que causó el error se convierte en una búsqueda de una aguja en un pajar. En otro repositorio, un desarrollador cambia una sola línea de texto en un archivo readme de un microservicio, lo que activa un pipeline de CI/CD de 40 minutos que vuelve a compilar y a desplegar los veinte microservicios del sistema. Estos problemas comunes de desarrollo no son fallos del stack tecnológico, sino fallos de la estrategia de control de versiones y de la arquitectura del repositorio. Los estándares de commits limpios y las configuraciones de monorrepositorios optimizadas son esenciales para crear pipelines de desarrollo robustos, escalables y cómodos para los desarrolladores en arquitecturas de microservicios. ## Tabla de contenidos * [Higiene de commits y el poder de la atomicidad](#git-hygiene) * [Estrategias de integración: Merge frente a Rebase](#merge-vs-rebase) * [Funciones avanzadas de Git: Rebase interactivo y Reflog](#advanced-git) * [Organización de microservicios: Monorrepositorios frente a Polirrepositorios](#monorepo-vs-polyrepo) * [Herramientas de monorrepositorio para PHP y Laravel](#php-monorepos) * [Optimización de pipelines de CI/CD en monorrepositorios](#monorepo-ci) * [Limitaciones y compromisos](#limitations) * [Conclusiones prácticas](#takeaways) --- ## Higiene de commits y el poder de la atomicidad El control de versiones es más que un simple mecanismo de copia de seguridad; es una herramienta de comunicación y un registro histórico. ### Commits atómicos * **Punto**: Un commit debe ser la unidad de código más pequeña posible que esté completa, sea funcional y contenga tanto el cambio como sus pruebas. * **Por qué es importante**: Si un commit es atómico, se puede revertir fácilmente sin romper otras características. También hace que `git bisect` (la búsqueda binaria de errores en el historial) sea extremadamente rápido. * **Ejemplo**: En lugar de combinar la refactorización, la corrección de un error y la actualización de una dependencia en un único commit gigante, divídalos en tres commits distintos. * **Consecuencia**: Las revisiones de código se vuelven más rápidas, el historial de código se mantiene limpio y las reversiones son sencillas. ### Conventional Commits Para estandarizar el historial de commits, los equipos utilizan la especificación **Conventional Commits**. Los mensajes siguen esta estructura: `(): `. * `feat`: Una nueva característica. * `fix`: Una corrección de errores. * `chore`: Tareas de mantenimiento, dependencias, configuraciones de compilación. * `docs`: Cambios en la documentación. * `refactor`: Cambios en el código que no corrigen un error ni añaden una característica. * `test`: Adición o corrección de pruebas. --- ## Estratégias de integración: Merge frente a Rebase La forma en que integra el historial de las ramas de nuevo en la rama principal determina la forma y la legibilidad de su repositorio. ``` Merge (Historial no lineal): A --- B --- C (main) \ / D --- E (feature) Rebase (Historial lineal): A --- B --- C --- D' --- E' (main/feature) ``` ### Git Merge * **Punto**: Combina ramas creando un nuevo \"commit de fusión\" (merge commit) que tiene múltiples commits padre. * **Por qué es importante**: Preserva el orden cronológico exacto de los eventos y representa la realidad histórica de cuándo las ramas se bifurcaron y se unieron. * **Consecuencia**: El historial se vuelve no lineal y se llena de commits del tipo \"Merge branch 'main' into feature\", lo que dificulta su lectura. ### Git Rebase * **Punto**: Mueve la base de su rama de características al último commit de la rama de destino, reescribiendo los commits sobre ella. * **Por qué es importante**: Crea un historial lineal y limpio donde cada característica parece haber sido construida secuencialmente. * **Consecuencia**: Reescribe los hashes de los commits. Si aplica un rebase sobre ramas públicas y compartidas, provocará conflictos para todos los demás miembros del equipo. **Regla: Nunca aplique rebase sobre ramas compartidas.** --- ## Funciones avanzadas de Git: Rebase interactivo y Reflog Las características avanzadas de Git ayudan a limpiar el código local antes de compartirlo con el equipo. ### Rebase interactivo (`git rebase -i`) * **Punto**: Permite reescribir, combinar, reordenar o eliminar commits en el historial de su rama local antes de subir los cambios. * **Por qué es importante**: Permite limpiar los commits de tipo \"wip\" (trabajo en progreso) y \"typo\" (fe de erratas), presenta un historial pulido en los pull requests y mantiene los commits atómicos. * **Ejemplo**: Ejecutar `git rebase -i HEAD~4` abre una lista de los últimos 4 commits: ```text pick a1b2c3d feat(auth): add google oauth provider squash d4e5f6g wip oauth login squash h7i8j9k fix typo in redirect url reword l0m1n2o feat(auth): add docs for oauth integration ``` Esto unifica los commits intermedios desordenados en el commit de la característica principal y reescribe el mensaje final. ### Cherry-Picking (`git cherry-pick`) * **Punto**: Añade un commit específico de una rama a su rama actual. * **Por qué es importante**: Útil para aplicar un hotfix de un error en una rama de producción sin fusionar toda la rama de la característica que lo contiene. ### Git Reflog (`git reflog`) * **Punto**: Un diario local que registra cada cambio realizado en las cabeceras de sus ramas, incluso si esos commits fueron eliminados o quedaron huérfanos debido a un rebase. * **Por qué es importante**: Si comete un error durante un rebase y pierde commits, puede usar `git reflog` para buscar el hash del commit original y restaurarlo con `git reset --hard `. --- ## Organización de microservicios: Monorrepositorios frente a Polirrepositorios Al desarrollar microservicios, debemos elegir cómo organizar nuestros repositorios. ### Polirrepositorio (un repositorio por servicio) * **Punto**: Cada microservicio tiene su propio repositorio aislado. * **Por qué es importante**: Límites claros, tamaños de clonación pequeños y pipelines de CI/CD aislados. * **Consecuencia**: Es más difícil compartir código (requiere publicar paquetes), dificulta los cambios que afectan a varios servicios y provoca discrepancias en las versiones de las dependencias comunes. ### Monorrepositorio (un único repositorio para todo) * **Punto**: Todos los microservicios, bibliotecas y gateways viven en un único repositorio. * **Por qué es importante**: Cambios simplificados que afectan a varios servicios, versiones de dependencias unificadas y uso compartido de código instantáneo sin tener que publicar paquetes externos. * **Consecuencia**: Repositorios de gran tamaño, configuraciones de CI/CD complejas y el peligro de difuminar los límites si los servicios se acoplan fuertemente a través de carpetas compartidas. --- ## Herramientas de monorrepositorio para PHP y Laravel A diferencia de JavaScript, donde son populares herramientas como Turborepo o Lerna, los desarrolladores de PHP pueden construir monorrepositorios robustos utilizando las características nativas de Composer. ### 1. Repositorios de rutas de Composer (Path Repositories) En lugar de publicar paquetes compartidos en Packagist, puede hacer referencia a directorios locales utilizando repositorios de tipo `path` en el archivo `composer.json` de su microservicio: ```json { "repositories": [ { "type": "path", "url": "../packages/shared-dto", "options": { "symlink": true } } ], "require": { "devsense/shared-dto": "*" } } ``` Composer crea un enlace simbólico (symlink) al paquete compartido, lo que le permite editar el código compartido y ver los cambios en el microservicio inmediatamente sin necesidad de ejecutar `composer update`. ### 2. Monorepo Builder Herramientas como **Monorepo Builder** de Symplify ayudan a fusionar configuraciones de composer, automatizar el versionado semántico de subpaquetes y mantener sincronizadas las versiones de las dependencias externas en todos los servicios. --- ## Optimización de pipelines de CI/CD en monorrepositorios El mayor cuello de botella de un monorrepositorio son los tiempos de compilación. Si cada commit activa pruebas para todos los servicios, el flujo de CI/CD se vuelve lento y costoso. * **Punto**: Activar los pasos de CI/CD de forma selectiva mediante el filtrado de rutas. * **Por qué es importante**: Limita el uso de recursos y mantiene rápidos los pipelines de despliegue. * **Ejemplo**: En GitHub Actions, configure los flujos de trabajo para que se ejecuten solo cuando cambien archivos en directorios específicos: ```yaml # .github/workflows/user-service.yml on: push: branches: [ main ] paths: - 'services/user-service/**' - 'packages/shared-dto/**' # Se activa si cambian las dependencias compartidas ``` * **Consecuencia**: Solo se prueban y compilan el servicio modificado y sus dependientes, reduciendo los tiempos de compilación de 30 minutos a 2 minutos. --- ## Demostración práctica de código Aquí se muestran plantillas de configuración reales para flujos de trabajo en monorrepositorios. ### 1. Flujo de trabajo de rebase interactivo en Git Para limpiar el historial de su rama antes de subir los cambios: ```bash # 1. Inicie el rebase interactivo para los últimos 3 commits git rebase -i HEAD~3 # 2. En el editor, cambie 'pick' por 'squash' (o 's') para los commits intermedios: # pick 82a17f2 feat: add database indexing # squash d928f01 fix syntax error in migration # squash a19f291 add missing index fields # 3. Guarde y cierre. Git le pedirá que edite el mensaje de commit combinado: # feat: add database indexing and migrations ``` ### 2. Configuración de CI selectiva en monorrepositorios (GitHub Actions) ```yaml # .github/workflows/checkout-service.yml name: Checkout Service CI on: push: branches: [ main, development ] paths: - 'services/checkout-service/**' - 'packages/shared-kernel/**' pull_request: branches: [ main, development ] paths: - 'services/checkout-service/**' - 'packages/shared-kernel/**' jobs: test: runs-on: ubuntu-latest steps: - name: Checkout Code uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: '8.5' extensions: mbstring, xml, bcmath, pdo_pgsql - name: Install Dependencies run: | cd services/checkout-service composer install --no-interaction --prefer-dist --optimize-autoloader - name: Run Tests run: | cd services/checkout-service ./vendor/bin/phpunit ``` --- ## Limitaciones y compromisos * **Riesgos del rebase**: El rebase es una operación destructiva porque reescribe el historial. Si fuerza la subida de cambios (`git push --force`) en una rama compartida sobre la que ha aplicado un rebase, puede sobrescribir el trabajo de otros desarrolladores. Use siempre `git push --force-with-lease` por seguridad. * **Escala del monorrepositorio**: A medida que un monorrepositorio crece, comandos como `git status` y `git fetch` pueden ralentizarse. Los archivos grandes y binarios deben gestionarse a través de Git LFS (Large File Storage) o mantenerse fuera del repositorio. * **Complejidad de CI/CD**: Gestionar las dependencias de rutas de forma manual en los pipelines de CI puede provocar fallos si un cambio en una biblioteca compartida no activa las pruebas en un servicio que depende de ella. El uso de herramientas como Turborepo o Nx ayuda a gestionar este árbol de dependencias automáticamente. --- ## Conclusiones prácticas 1. **Mantenga los commits atómicos**: Un cambio lógico por commit. Escriba los mensajes en modo imperativo (por ejemplo, `feat(auth): add token verification`, no `added verification`). 2. **Rebase en local, Merge en público**: Mantenga las ramas de características lineales con `git rebase`, pero fusiónelas en las ramas principales con commits de fusión explícitos (`git merge --no-ff`) para preservar los puntos de integración. 3. **Use Path Repositories para monorrepositorios PHP**: Enlace simbólicamente los paquetes compartidos en Composer para permitir ediciones locales inmediatas. 4. **Implemente filtrado de rutas en CI**: Evite el desperdicio de recursos dirigiendo los pipelines únicamente a los directorios modificados. 5. **Use `git push --force-with-lease`**: Nunca suba cambios a ciegas; asegúrese de no sobrescribir el trabajo remoto de sus compañeros.