GitHub Merge Queue: configuración, workflows y errores
Última actualización
Cuando muchas personas fusionan cambios en main a lo largo del día, un PR que superó el CI contra el main de ayer puede romper el de hoy. Una cola de fusión resuelve este problema: prueba cada PR combinado con los PR que están delante de él y solo lo fusiona si ese resultado combinado supera las pruebas. Esta guía explica cómo funciona, cómo configurarla y qué cambios necesita en su CI.
El problema que resuelve
La protección de ramas puede exigir que los PR estén "actualizados" antes de fusionarse. Es seguro, pero obliga a todos a actualizar su rama y volver a ejecutar el CI cada vez que alguien más fusiona, una carrera que empeora a medida que crece el equipo. Sin esa regla, dos PR que superan las pruebas por separado pueden romper main juntos, por ejemplo, dos cambios en la firma de la misma función en archivos distintos.
Cómo funciona la cola
- Un desarrollador hace clic en "Merge when ready" (o añade el PR a la cola).
- GitHub crea una rama temporal que contiene la rama base, los PR que están delante en la cola y este PR. Los nombres de rama tienen el formato
gh-readonly-queue/main/pr-123-<sha>. - Activa sus workflows con el evento
merge_groupsobre esa rama. - Si las comprobaciones obligatorias superan las pruebas, el PR se fusiona. Si fallan, el PR se retira de la cola y los PR que están detrás se reconstruyen sin él.
Los desarrolladores siguen ejecutando las comprobaciones de PR como antes. La cola añade una segunda comprobación final sobre el resultado combinado.
Disponibilidad: la documentación de GitHub indica que las colas de fusión están disponibles para repositorios públicos de una organización y para repositorios privados en GitHub Enterprise Cloud. Consulte los requisitos de plan actuales en la documentación antes de planificar su uso.
Paso 1: Haga que los workflows se ejecuten con merge_group
Este es el paso que más equipos pasan por alto. Las comprobaciones de estado obligatorias en una cola solo se informan si el workflow se activa con merge_group. Si no es así, el PR en cola espera comprobaciones que nunca se ejecutan.
on:
pull_request:
merge_group:
types: [checks_requested]
Todo workflow que aporte una comprobación obligatoria necesita este disparador, incluidas las comprobaciones ligeras como lint o un job de resumen tests-passed. Tenga cuidado con los filtros paths: si una comprobación obligatoria se omite por un filtro de rutas, la cola sigue esperando a que esa comprobación informe. Pruebe esto primero en una rama de poco tráfico.
Revise también actions/checkout. En una ejecución de merge_group, github.sha es el commit de fusión de la rama temporal, por lo que el checkout predeterminado obtiene el código correcto. Evite los pasos que asumen que existe github.event.pull_request; no existe para merge_group. Para la lógica basada en diferencias, como las compilaciones afectadas, compare con github.event.merge_group.base_sha.
Paso 2: Actívela en un ruleset o en la protección de ramas
En la configuración del repositorio, en Rules (rulesets) o Branches (protección de ramas), active "Require merge queue" para su rama predeterminada y elija estas opciones:
| Ajuste | Qué hace | Opción habitual |
|---|---|---|
| Método de fusión | Merge, squash o rebase para los PR en cola | Squash, para mantener su historial |
| Concurrencia de compilación | Cuántas entradas de la cola se prueban a la vez | De 3 a 5 |
| Tamaño mínimo de grupo | Lote más pequeño que se fusiona de una vez | 1 |
| Tamaño máximo de grupo | Lote más grande que se fusiona de una vez | De 3 a 5 en repositorios muy activos |
| Tiempo de espera para alcanzar el mínimo | Cuánto tiempo esperar a que se complete un grupo | 5 minutos o menos |
| Tiempo límite de comprobaciones de estado | Marcar como fallida una entrada de la cola si las comprobaciones tardan demasiado | Aproximadamente el doble de su tiempo de CI |
| Fusionar solo los PR que no fallan | Si un PR fallido dentro de un grupo bloquea a los demás | Activar |
Los valores predeterminados son conservadores. La concurrencia de compilación controla el rendimiento: con 5 entradas simultáneas y un CI de 10 minutos, la cola puede fusionar mucho más rápido que una a una, porque cada entrada se prueba de forma especulativa sobre las anteriores.
Paso 3: Comprobaciones obligatorias que coincidan
Añada las comprobaciones que desee aplicar en la rama de la cola como comprobaciones de estado obligatorias en el mismo conjunto de reglas. Utilice nombres estables; una matriz genera nombres que cambian cuando cambia la matriz. Un único job de resumen soluciona esto; consulte cómo hacer bien las compilaciones con matriz.
Decida qué comprobaciones ejecutar dos veces. El patrón habitual: ejecute las comprobaciones rápidas (lint, pruebas unitarias) tanto en la PR como en la cola; ejecute las comprobaciones lentas (pruebas end-to-end completas, multi-SO) solo en la cola, para que cada PR no tenga que asumir su coste. Así, la cola concentra el coste y la retroalimentación de la PR sigue siendo rápida.
Efecto en el coste y la velocidad
Las colas de fusión añaden ejecuciones: cada PR en cola ejecuta al menos una vez más el CI. Con compilaciones especulativas, un fallo en una entrada anterior cancela y reinicia las siguientes. Estimaciones:
- Los minutos adicionales por PR fusionada equivalen aproximadamente a una ejecución completa del CI de las comprobaciones que exige la cola.
- Si los fallos son frecuentes, los reinicios multiplican ese coste. Las pruebas inestables son la causa principal; consulte cómo tratar las pruebas inestables.
- Los grupos más grandes (batching) reducen el número de ejecuciones: con un tamaño máximo de grupo de 5, cinco PR pueden compartir una misma ejecución de CI, a costa de un diagnóstico más difícil cuando falla.
Modélelo con el previsor de minutos de CI: PR por día x minutos de CI de la cola x tasa. Después, compárelo con el coste de una main rota, que normalmente bloquea a todo el equipo.
Errores frecuentes
- Las comprobaciones nunca se inician: falta el disparador
merge_group. - Comprobaciones obligatorias omitidas: un job omitido por
if:puede aparecer como omitido, lo que en algunas configuraciones cuenta como aprobado para las comprobaciones obligatorias. Use el patrón de job de resumen conif: always(). - Secretos y permisos:
merge_groupse ejecuta en el contexto del repositorio, con acceso normal; revise a qué secretos acceden esos workflows. - Bots y actualizaciones de dependencias: las PR de Dependabot funcionan con la cola; active la fusión automática en ellas en lugar de fusionarlas a mano. Consulte configuración de Dependabot.
- Revisiones obligatorias y CODEOWNERS siguen aplicándose antes de que una PR pueda entrar en la cola. Consulte CODEOWNERS y protección de ramas.
- Correcciones urgentes: los administradores pueden saltarse la cola o adelantarse a ella según su conjunto de reglas; defina la política de antemano.
Alternativas
Si no puede usar la cola de fusión de GitHub, herramientas de terceros ofrecen un comportamiento similar: Mergify, Aviator, la cola de Graphite y bots tipo Bors. Funcionan creando el mismo tipo de rama temporal combinada. Las consideraciones anteriores, la configuración de disparadores y el coste, se aplican a todas ellas.
Preguntas frecuentes
¿Necesito activar la cola para usar la fusión automática?
No. La fusión automática fusiona cuando se cumplen los requisitos. Con una cola habilitada, en lugar de fusionar, añade la PR a la cola.
¿La cola hace rebase de mi PR?
Fusiona la PR sobre la rama temporal; el método final depende de la configuración de método de fusión. La rama de su PR no se actualiza.
¿Qué pasa si las comprobaciones pasan en la PR pero fallan en la cola?
La PR se retira de la cola. Eso significa que la combinación con otros cambios rompió algo, que es precisamente el propósito de la cola. Actualice la rama, corrija el problema y vuelva a ponerla en cola.
¿Funciona con despliegues obligatorios?
Los entornos pueden formar parte de las comprobaciones obligatorias, pero pruébelo en una rama de poco tráfico antes de depender de ello.
Mida el efecto
Registre el tiempo desde "listo para fusionar" hasta la fusión, y el número de incidentes de main rota antes y después. Cuando el CI de la cola es el cuello de botella, un runner más rápido reduce la espera de todos: el modo de comparación de compiler.dev le permite probar el workflow de su cola en máquinas más rápidas y comparar el coste por ejecución.
Relacionado
- ¿Qué es una cola de fusión en GitHub?Una cola de fusión prueba cada pull request con la última versión de main y los PR anteriores, para que main nunca se rompa. Así funciona.
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.