Administración de una cola de fusión mediante combinación

Acerca de las colas de fusión mediante combinación

Una cola de combinación ayuda a aumentar la velocidad mediante la automatización de las combinaciones de solicitudes de incorporación de cambios en una rama ocupada y asegurarse de que la rama nunca se interrumpe por cambios incompatibles.

La cola de combinación proporciona las mismas ventajas que requerir que las ramas estén actualizadas antes de combinar la protección de la rama, pero no requiere que un autor de la solicitud de incorporación de cambios actualice su rama de solicitud de incorporación de cambios y espere a que finalicen las comprobaciones de estado antes de intentar combinar.

El uso de una cola de combinación es especialmente útil en las ramas que tienen un número relativamente alto de solicitudes de incorporación de cambios que se combinan cada día de muchos usuarios diferentes.

Cuando una solicitud de incorporación de cambios ha superado todas las comprobaciones de protección de rama necesarias, el usuario con acceso de escritura al repositorio puede agregar la solicitud de incorporación de cambios a la cola. La cola de combinación garantizará que los cambios de la solicitud de incorporación de cambios pasen todas las comprobaciones de estado necesarias cuando se aplican a la versión más reciente de la rama de destino y a las solicitudes de incorporación de cambios que ya estén en la cola.

Una cola de combinación puede usar las GitHub Actions o tu propio proveedor de CI para ejecutar comprobaciones necesarias en las solicitudes de incorporación de cambios en una cola de combinación. Para obtener más información, vea «Documentación de GitHub Actions».

Para más información sobre cómo combinar una solicitud de incorporación de cambios mediante una cola de combinación, consulte "Combinación de una solicitud de incorporación de cambios con una cola de fusión mediante combinación".

Configuración de flujos de trabajo de integración continua (CI) para colas de combinación

Desencadenamiento de comprobaciones del grupo de fusión mediante combinación con GitHub Actions

Cuando se agrega una solicitud de incorporación de cambios a una cola de fusión debes usar el evento merge_group para desencadenar un flujo de trabajo de GitHub Actions.

Un flujo de trabajo que informa de una comprobación requerida por las protecciones de la rama de destino tendría este aspecto:

on:
  pull_request:
  merge_group:

Para obtener más información sobre el evento merge_group, consulta "Eventos que desencadenan flujos de trabajo".

Desencadenamiento de comprobaciones del grupo de combinación con otros proveedores de CI

Con terceros proveedores de CI, tendrás que actualizar la configuración de CI para que se ejecute cuando se inserta una rama que comience con el prefijo especial gh-readonly-queue/{base_branch}. Estas son las ramas temporales que se crean en tu nombre mediante una cola de combinación y contienen una sha que es distinta de la solicitud de incorporación de cambios.

Administración de una cola de fusión mediante combinación

Los administradores del repositorio pueden exigir una combinación si habilitan el valor de protección de rama "Requerir cola de combinación" en las reglas de protección de la rama base. Para obtener más información, vea «Administrar una regla de protección de rama».

Una vez que hayas habilitado el valor "Requerir cola de combinación", también puedes acceder a los siguientes valores de configuración:

• Método de combinación: selecciona el método que se va a usar al combinar solicitudes de incorporación de cambios en cola: fusión mediante combinación, fusión mediante cambio de base o fusión mediante combinación con "squash".

• Simultaneidad de compilación: el número máximo de webhooks de merge_group que se envían (entre 1 y 100), limitando la cantidad total de compilaciones de CI simultáneas. Esto afecta a la velocidad de las combinaciones que una cola de combinaciones puede completar.

• Solo combinar solicitudes de incorporación de cambios sin errores: este valor determina la forma en que una cola de combinación forma los grupos de solicitudes de incorporación de cambios que se van a combinar.

  ¿Habilitado?	Descripción
  Sí	Todas las solicitudes de incorporación de cambios deben satisfacer las comprobaciones necesarias para poder combinarse.
  No	Las solicitudes de incorporación de cambios que no hayan superado las comprobaciones necesarias se pueden agregar a cualquier grupo, siempre y cuando la última solicitud de incorporación de cambios del grupo haya superado las comprobaciones necesarias. Si la última solicitud de incorporación de cambios del grupo ha superado las comprobaciones necesarias, esto significa que se han superado las comprobaciones para el conjunto combinado de cambios del grupo de combinación. Podría ser útil dejar esta casilla sin seleccionar si se producen errores intermitentes en las pruebas, pero no quieres que los falsos negativos interrumpan la cola.

• Tiempo de espera de comprobación de estado: elige durante cuánto tiempo debe la cola esperar una respuesta de CI antes de suponer que se ha producido un error en las comprobaciones.

• Límites de combinación: selecciona el número mínimo y máximo de solicitudes de incorporación de cambios que se van a combinar en la rama base al mismo tiempo (entre 1 y 100) y un tiempo de espera después del cual la cola debe dejar de esperar más entradas y realizar la combinación con menos del número mínimo.

Límite de combinación	Caso de uso
Número máximo de solicitudes de incorporación de cambios que se combinan	Puedes especificar un tamaño de grupo máximo, lo que resulta útil si las combinaciones en la rama base desencadenan una implementación y quieres asegurarte de que no vas a implementar demasiados cambios a la vez.
Número mínimo de solicitudes de incorporación de cambios que se combinan	Puedes especificar un tamaño de grupo mínimo, lo que resulta útil si las combinaciones con una rama base desencadenan un largo proceso de implementación o compilación de CI, y no desea mantener las siguientes entradas en la cola.
Tiempo de espera	Puede especificar un tiempo de espera para alcanzar el tamaño mínimo del grupo, lo que permite que grupos más pequeños se combinen si no hay más solicitudes de incorporación de cambios en cola dentro del límite de tiempo especificado.

Funcionamiento de las colas de combinación

A medida que se agregan solicitudes de incorporación de cambios a la cola de mezcla, esta garantiza que se combinan de tal forma que las primeras en entrar son las primeras en salir y que siempre se cumplen las comprobaciones necesarias.

Las colas de combinación crean ramas temporales con un prefijo especial para validar los cambios de la solicitud de incorporación de cambios. Cuando se agrega una solicitud de incorporación de cambios a la cola de combinación, los cambios que se realizan en dicha solicitud se agrupan en una merge_group con la versión más reciente debase_branch, así como los cambios de las solicitudes que se encuentren delante de ella en la cola. GitHub combinará todos estos cambios en base_branch una vez que se superen las comprobaciones que requieren las protecciones de rama de base_branch.

Para más información sobre los métodos de fusión mediante combinación, consulta "Acerca de las fusiones de las solicitudes de extracción".

Integración continua correcta

Cuando se agregan varias solicitudes de incorporación de cambios a la cola de combinación y cuando las ramas merge_group temporales tienen resultados correctos de la integración continua, ambas se combinan. En el escenario siguiente, se agregan correctamente dos solicitudes de incorporación de cambios a la cola y se combinan en la rama de destino.

1. El usuario agrega la solicitud de incorporación de cambios 1 a la cola de combinación.
2. La cola de combinación crea una rama temporal con el prefijo de main/pr-1 que contiene los cambios de código de la rama de destino y la solicitud de incorporación de cambios 1. Se envía un evento de webhook merge_group del tipo checks_requested y la cola de combinación esperará una respuesta del proveedor de CI.
3. El usuario agrega la solicitud de incorporación de cambios 2 a la cola de combinación.
4. La cola de combinación crea una rama temporal con el prefijo main/pr-2 que contiene los cambios de código de la rama de destino, la solicitud de incorporación de cambios 1 y la solicitud de incorporación de cambios 2, y envía los webhooks.
5. Cuando la API GitHub recibe respuestas de una integración continua satisfactoria en las merge_group ramas y main/pr-1 y main/pr-2, la rama main/pr-2 temporal se combinará en la rama de destino. La rama de destino ahora contiene los cambios de la solicitudes de incorporación de cambios 1 y 2.

Integración continua con errores

Después de agrupar una solicitud de incorporación de cambios con la versión más reciente de la rama de destino y los cambios anteriores en la cola, si hay comprobaciones de estado necesarias con errores o conflictos con la rama base, la solicitud de incorporación de cambios de la cola se eliminará. La línea de tiempo de la solicitud de incorporación de cambios mostrará el motivo por el que esa solicitud se ha eliminado de la cola.

En el escenario siguiente se describe lo que sucede cuando una ci notifica un estado de error sobre una solicitud de incorporación de cambios.

1. El usuario agrega la solicitud de incorporación de cambios 1 a la cola de combinación.
2. La cola de combinación crea una rama temporal con el prefijo de main/pr-1 que contiene los cambios de código de la rama de destino y la solicitud de incorporación de cambios 1. Se envía un evento de webhook merge_group del tipo checks_requested y la cola de combinación esperará una respuesta del proveedor de CI.
3. El usuario agrega la solicitud de incorporación de cambios 2 a la cola de combinación.
4. La cola de combinación crea una rama temporal con el prefijo main/pr-2 que contiene los cambios de código de la rama de destino, la solicitud de incorporación de cambios 1 y la solicitud de incorporación de cambios 2, y envía los webhooks.
5. Cuando la API GitHub recibe un estado de error para main/pr-1, la cola de combinación quita automáticamente la solicitud de incorporación de cambios 1 de la cola de combinación.
6. La cola de combinación vuelve a crear la rama temporal con el prefijo main/pr-2 para que solo contenga los cambios de código de la rama de destino y la solicitud de incorporación de cambios  2.
7. Cuando la API GitHub recibe respuestas de una integración continua satisfactoria en la merge_group ramas main/pr-2, la rama temporal main/pr-2 se combinará en la rama de destino sin la inclusión de la solicitud de incorporación de cambios 1.

Hay varias razones por las que se puede quitar una solicitud de incorporación de cambios de una cola de combinación:

• El servicio de CI configurado ha notificado errores de prueba para un grupo de combinación
• Se ha agotado el tiempo de espera de un resultado de CI correcto según la configuración de tiempo de espera configurada.
• Usuario que solicita una eliminación mediante la API o la interfaz de la cola de combinación
• Error de protección de rama que no se ha podido resolver automáticamente

Subir al principio de la cola

Al agregar una solicitud de incorporación de cambios a una cola de combinación, hay una opción para mover la solicitud al principio de la cola.

En el escenario siguiente se describe lo que sucede cuando un usuario sube o baja en la cola.

1. El usuario agrega la solicitud de incorporación de cambios 1 a la cola de combinación.
2. La cola de combinación crea una rama temporal con el prefijo de main/pr-1 que contiene los cambios de código de la rama de destino y la solicitud de incorporación de cambios 1. Se envía un evento de webhook merge_group del tipo checks_requested y la cola de combinación esperará una respuesta del proveedor de CI.
3. El usuario agrega la solicitud de incorporación de cambios 2 a la cola de combinación.
4. La cola de combinación crea una rama temporal con el prefijo main/pr-2 que contiene los cambios de código de la rama de destino, la solicitud de incorporación de cambios 1 y la solicitud de incorporación de cambios 2, y envía los webhooks.
5. El usuario agrega la solicitud de incorporación de cambios 3 a la cola de combinación con la opción de salto, lo que introduce una interrupción en el gráfico de confirmación.
6. La cola de combinación crea una rama temporal con el prefijo main/pr-3 que contiene los cambios de código de la rama de destino y la solicitud de incorporación de cambios 3, y envía los webhooks.
7. La cola de combinación vuelve a crear la rama temporal con los prefijos main/pr-1 y main/pr-2, que contiene los cambios de la solicitud de incorporación de cambios 3, y envía los webhooks.

Información adicional

• "Combinación de una solicitud de incorporación de cambios con una cola de fusión mediante combinación"
• "Acerca de las ramas protegidas"