Merge Request (MR): qué es, cómo crear y el proceso de revisión

¿Qué es un Merge Request (MR)?

Merge Request (MR) — una solicitud para integrar cambios de una rama de Git a otra, que inicia el proceso de revisión de código y comprobaciones automatizadas. A diferencia de la fusión directa a través de la consola, MR crea un procedimiento formal: el desarrollador describe los cambios, asigna revisores, inicia CI/CD y recibe comentarios antes de aplicar los cambios. Este es un elemento clave de GitLab, pero el mecanismo equivalente en GitHub se llama Pull Request (PR).

Según GitLab Documentation, 2026, se crean más de 80 millones de Merge Requests en GitLab anualmente. Cada MR contiene cuatro componentes principales: una descripción con el contexto de los cambios, una lista de commits, la diferencia de código (diff) y la discusión (hilo de discusión). Sin uno de estos elementos, el MR se considera incompleto.

Merge Request (MR) resuelve tres tareas: evita cambios directos en ramas protegidas (main, develop), proporciona control de calidad a través de la revisión y preserva el historial de discusiones para futuros desarrolladores. En GitLab, el estado del MR se muestra en la interfaz con indicadores de color: gris para Draft, naranja para pendiente, verde para Approved, púrpura para Merged y rojo para Closed.

Terminología: MR, PR y CR

En diferentes plataformas Git, Merge Request se llama de distintas maneras. GitLab utiliza “Merge Request” (MR), GitHub utiliza “Pull Request” (PR). La analogía es Change Request (CR) en Gerrit. Los tres denotan el mismo proceso: una solicitud para integrar cambios mediante revisión de código. La elección del término depende solo de la plataforma utilizada en el proyecto.

# Crear una rama con cambios
git checkout -b feature/add-auth
git commit -m "Add OAuth2 authentication flow"
git push origin feature/add-auth

# Puedes crear un MR mediante la interfaz de GitLab/GitHub o CLI:
gh pr create --title "Add OAuth2 authentication flow" \
  --body "Implements OAuth2 with Google and Apple providers" \
  --reviewer "team-lead"

MR vs PR: ¿cuál es la diferencia entre GitLab y GitHub

Merge Request en GitLab y Pull Request en GitHub son mecanismos funcionalmente idénticos con diferentes nombres. La diferencia se debe a la historia: GitLab se posicionó originalmente como una alternativa Self-Hosted a GitHub y eligió el término “merge request” para el proceso de fusión. GitHub, lanzado antes, utilizó “pull request” — una solicitud para “traer” (pull) los cambios a la rama principal.

Según GitHub Docs, 2024, ambas herramientas admiten el mismo conjunto de funciones: descripción con Markdown, asignación de revisores, comentarios en líneas específicas de código, estados de verificación y fusión automática cuando se cumplen las condiciones. Las diferencias se relacionan con la interfaz y las capacidades adicionales.

Cómo crear un Merge Request: guía paso a paso

Crear un Merge Request (MR) comienza con la publicación de una rama con cambios en el repositorio remoto. Después del push a GitLab o GitHub, la interfaz muestra un botón “Create Merge Request” o “Compare & Pull Request”. El desarrollador completa la descripción, especifica la rama de destino (generalmente develop o main), asigna revisores y adjunta etiquetas.

Según GitLab Documentation, 2025, un MR estándar contiene un título de hasta 72 caracteres, una descripción con plantilla y un enlace al issue. La descripción debe responder a las preguntas: qué se hizo, por qué, cómo se probó. GitLab admite el cierre automático de issues al fusionar usando las palabras clave Closes, Fixes, Resolves.

# Ejemplo de plantilla .gitlab/merge_request_templates/default.md
## What does this MR do?

[Breve descripción de los cambios: qué y por qué]

## How to test

1. Ejecutar ./gradlew test
2. Verificar LoginActivity con el token de prueba
3. Asegurarse de que no hay regresión en AuthManager

## Related issues

Closes #142

Ciclo de vida del MR: desde Draft hasta Merged

Merge Request (MR) pasa por cinco estados en GitLab. El primero es Draft (borrador), marcado con el prefijo “Draft:” en el título, que bloquea la fusión. Cuando está listo, el desarrollador elimina Draft y el MR pasa al estado Opened: comienza la revisión de código y se inicia el pipeline CI/CD.

Según GitLab Docs, 2024, en el estado Opened, los revisores examinan el diff, dejan comentarios y solicitan cambios a través de Resolve Threads. Cuando todos los hilos están resueltos y CI/CD pasa correctamente, el desarrollador responsable establece Approve. Después de eso, el MR se puede fusionar usando el botón Merge, o se puede esperar la fusión automática (Auto-merge).

GitLab admite tres opciones de estado final: Merged (fusionado correctamente), Closed (cerrado sin fusión, por ejemplo, al abandonar una funcionalidad) y Reopened (reapertura después del cierre). Cada estado se registra en la Línea de tiempo de actividad del MR para auditoría.

Estados automáticos y disparadores

GitLab actualiza automáticamente el estado del Merge Request ante eventos: al hacer push de nuevos commits se restablecen las Approvals, al pasar el pipeline CI el estado pasa a Pipeline passed, al fallar — Pipeline failed (la fusión se bloquea). Se puede configurar Auto-merge: el MR se fusiona automáticamente después de CI exitoso y de recibir todas las aprobaciones requeridas.

• Draft — borrador, CI se ejecuta pero la fusión está bloqueada
• Opened — listo para revisión, revisores asignados, pipeline activo
• Approved — se ha recibido el número requerido de aprobaciones
• Merged — cambios fusionados en la rama de destino
• Closed — cerrado sin fusión

Reglas de revisión de código en Merge Request

La revisión de código en Merge Request (MR) es una etapa obligatoria en la mayoría de los proyectos comerciales. Según SmartBear, 2023, la revisión de código con MR reduce la cantidad de defectos en un 30–60% y acelera la incorporación de nuevos desarrolladores. La regla principal es que cada MR sea revisado por al menos uno, preferiblemente dos desarrolladores que no hayan participado en la escritura del código.

La revisión de MR incluye cinco criterios: corrección lógica, cumplimiento del estilo de código, cobertura de pruebas, seguridad y rendimiento. En GitLab se pueden configurar Required Approvals — la cantidad obligatoria de aprobaciones antes de fusionar, por ejemplo, 2 aprobaciones para main y 1 para develop.

La discusión en MR se realiza en Threads — comentarios en líneas específicas de código. Cada hilo debe resolverse antes de la fusión. Para acelerar las revisiones, se recomienda limitar el tamaño del MR: 200–400 líneas de cambios. Según Google Research (2022), los MR de más de 400 líneas se revisan un 30% menos eficazmente.

Pipeline CI/CD en Merge Request

Al crear un Merge Request (MR), el pipeline CI/CD se inicia automáticamente. En GitLab esto ocurre a través del archivo .gitlab-ci.yml, en GitHub a través del workflow de GitHub Actions. El pipeline incluye compilación del proyecto, pruebas unitarias, linters, análisis estático (SAST) y verificación de cobertura de código.

Según GitLab Blog, 2024, el estado del pipeline se muestra directamente en el MR: marca verde (passed), cruz roja (failed) o círculo amarillo (running). Si el pipeline falla, GitLab bloquea el botón Merge hasta que se solucione. En la configuración se puede habilitar “Merge when pipeline succeeds” — fusión automática después de un pipeline exitoso.

# .gitlab-ci.yml — ejemplo para un proyecto Android
test:
  stage: test
  script:
    - ./gradlew ktlintCheck
    - ./gradlew testDebugUnitTest
  only:
    - merge_requests

build:
  stage: build
  script:
    - ./gradlew assembleDebug
  only:
    - merge_requests

Métodos de fusión: Squash, Merge Commit, Fast-Forward

GitLab y GitHub ofrecen tres métodos de fusión para Merge Request. La elección depende de la política del equipo y la limpieza deseada del historial. Merge Commit crea un commit de fusión separado, conservando todo el historial de la rama de funcionalidad. Squash combina todos los commits de la rama en un solo commit en la rama de destino. Fast-Forward aplica los commits de forma lineal sin un commit de fusión.

Según GitLab Docs, 2025, Squash es preferible para proyectos con alta densidad de commits (20+ commits en una rama de funcionalidad). Fast-Forward es obligatorio para Trunk-Based Development. Merge Commit se utiliza en Git Flow para conservar la semántica de ramificación.

• Merge Commit — conserva el historial, crea un commit de fusión, adecuado para Git Flow
• Squash — combina todos los commits en uno, historial limpio, pierde commits intermedios
• Fast-Forward — historial lineal sin commit de fusión, obligatorio en TBD

Mejores prácticas: cómo escribir un buen MR

Un Merge Request (MR) de calidad reduce el tiempo de revisión y la cantidad de errores. La primera regla es que un MR resuelve una tarea. Si los cambios afectan múltiples funcionalidades no relacionadas, deben dividirse en MR separados. Segundo, el título del MR debe ser informativo: “Add OAuth2 authentication with Google provider” en lugar de “Fix stuff” o “Update code”.

Según Google Engineering Practices, 2024, un buen MR contiene una descripción del contexto: por qué los cambios son necesarios, cómo se probaron y qué riesgos existen. El tamaño del MR no debe exceder las 400 líneas de cambios. Si el volumen es mayor, la tarea debe descomponerse en subtareas. Para documentación y pruebas, las excepciones son aceptables pero con explicación.

Merge Request (MR) debe incluir pruebas automatizadas para la nueva funcionalidad. En GitLab se puede configurar la política Coverage Check: el MR se bloquea automáticamente si la cobertura de código cae por debajo de un umbral (por ejemplo, 80%). Esto garantiza que la nueva funcionalidad no reduzca la calidad general del proyecto.

• Un MR — una tarea: descomponga los cambios grandes en varios MR pequeños
• Descripción con plantilla: use .gitlab/merge_request_templates para uniformidad
• Tamaño hasta 400 líneas: los MR grandes se revisan más lentamente y con más errores
• Pruebas obligatorias: las nuevas funcionalidades deben cubrirse con pruebas unitarias

Plantillas de descripción de MR

GitLab admite plantillas de Merge Request a través de archivos .gitlab/merge_request_templates/. La plantilla incluye secciones: qué se hizo, cómo probar, tareas relacionadas y lista de verificación. El uso de plantillas acelera la creación de MR y garantiza que los desarrolladores no olviden incluir información importante. En la descripción del MR se deben especificar los issues relacionados (Closes #N) para el cierre automático de tareas al fusionar.