Cómo usar el activador de Gerrit en Code Stream para ejecutar una canalización

Como administrador o desarrollador de Code Stream puede integrar Code Stream con el ciclo de vida de revisión de código de Gerrit mediante el activador de Gerrit. El evento acciona una canalización para que se ejecute al crear un conjunto de revisiones, publicar borradores, combinar cambios de código en el proyecto de Gerrit o insertar cambios directamente en la rama de Git.

Al agregar el activador de Gerrit, debe seleccionar un agente de escucha de Gerrit y un proyecto de Gerrit en el servidor, y debe configurar los eventos de Gerrit. En la definición del agente de escucha de Gerrit, seleccione un endpoint de Gerrit. Si es necesario actualizar el endpoint de Gerrit después de conectar el agente de escucha, primero se debe desconectar y, a continuación, actualizar el endpoint.

En este ejemplo, se configura un agente de escucha de Gerrit en primer lugar y, a continuación, se utiliza ese agente en un activador de Gerrit con dos eventos en tres canalizaciones diferentes.

Requisitos previos

• Compruebe si es un miembro de un proyecto en Code Stream. Si no lo es, solicite al administrador de Code Stream que lo agregue como miembro de un proyecto. Consulte Cómo agregar un proyecto en Code Stream.
• Asegúrese de que tiene un endpoint de Gerrit configurado en Code Stream. Consulte Cómo se integra Code Stream con Gerrit.
• Compruebe que conoce la versión de Gerrit.
• Para que se activen las canalizaciones, compruebe que las propiedades de entrada de la canalización estén establecidas en Gerrit, lo que permite que la canalización reciba los parámetros de Gerrit como entradas cuando se ejecuta la canalización.

  

  Para obtener información sobre los parámetros de entrada, consulte Planificar una compilación nativa de CICD en Code Stream antes de agregar tareas manualmente.

Procedimiento

1. En Code Stream, haga clic en Activadores > Gerrit.
2. (opcional) Haga clic en la pestaña Agentes de escucha y, a continuación, haga clic en Nuevo agente de escucha.
   Nota: Omita este paso si el agente de escucha de Gerrit que tiene pensado usar para el activador de Gerrit ya está definido.
   1. Seleccione un proyecto.
   2. Introduzca un nombre para el agente de escucha de Gerrit.
   3. Seleccione un endpoint de Gerrit.
   4. Introduzca el token de API.
      El token de API de CSP lo autentica para las conexiones de API externas con Code Stream. Para obtener el token de API:

      1. Haga clic en Generar token.
      2. Introduzca la dirección de correo electrónico asociada con el nombre de usuario y la contraseña y haga clic en Generar.
         El token que se genera es válido durante seis meses. También se conoce como token de actualización.

         • Para mantener el token como una variable para un uso futuro, haga clic en Crear variable, introduzca un nombre para la variable y haga clic en Guardar.
         • Para conservar el token como valor de texto para usarlo en el futuro, haga clic en Copiar y pegue el token en un archivo de texto para guardarlo de forma local.

         Puede elegir entre crear una variable y almacenar el token en un archivo de texto para utilizarlo en el futuro.
      3. Haga clic en Cerrar.
      Si creó una variable, el token de API muestra el nombre de la variable que introdujo mediante el enlace de símbolo de dólar. Si ha copiado el token, el token de API muestra el token enmascarado.

      

   5. Para validar los detalles del endpoint y el token, haga clic en Validar.
      El token caduca tras 90 días.
   6. Haga clic en Crear.
   7. En la tarjeta del agente de escucha, haga clic en Conectar.
      El agente de escucha inicia la supervisión de toda la actividad en el servidor de Gerrit y escucha los activadores habilitados en ese servidor. Para dejar de escuchar un activador en ese servidor, desactive el activador.

      Nota: Para actualizar un endpoint de Gerrit que está conectado a un agente de escucha, se debe desconectar antes de actualizar el endpoint.

      • Haga clic en Configurar > Activadores > Gerrit .
      • Haga clic en la pestaña Agentes de escucha.
      • Haga clic en Desconectar en el agente de escucha que está conectado al endpoint que desea actualizar.
3. Haga clic en la pestaña Activadores y, a continuación, haga clic en Nuevo activador.
4. Seleccione un proyecto del servidor de Gerrit.
5. Introduzca un nombre.
   El nombre del activador de Gerrit debe ser exclusivo.
6. Seleccione un agente de escucha de Gerrit configurado.
   Con el uso del agente de escucha de Gerrit, Code Stream proporciona una lista de proyectos de Gerrit que están disponibles en el servidor.
7. Seleccione un proyecto del servidor de Gerrit.
8. Introduzca la rama en el repositorio que supervisará el agente de escucha de Gerrit.
9. (opcional) Proporcione inclusiones o exclusiones de archivos como condiciones para el activador.
   • Proporcione inclusiones de archivos para que se activen las canalizaciones. Cuando cualquiera de los archivos de una confirmación coincida con los archivos especificados en las expresiones regulares o rutas de inclusión, se activarán las canalizaciones. Con una expresión regular especificada, Code Stream solo activa canalizaciones con nombres de archivo en el conjunto de cambios que coinciden con la expresión proporcionada. El filtro de expresiones regulares es útil cuando se configura un activador para varias canalizaciones en un solo repositorio.
   • Proporcione exclusiones de archivos para impedir que se activen las canalizaciones. Cuando todos los archivos de una confirmación coinciden con los archivos especificados en las rutas de exclusión o en las expresiones regulares, no se activarán las canalizaciones.
   • Priorizar exclusión: cuando se activa, garantiza que las canalizaciones no se activen. Las canalizaciones no se activarán aunque alguno de los archivos de una confirmación coincida con los archivos especificados en las rutas de exclusión o en las expresiones regulares. La configuración predeterminada para Priorizar exclusión es desactivada.

   Si las condiciones cumplen con la inclusión y la exclusión de archivos, las canalizaciones no se activan.

   En el siguiente ejemplo, tanto las inclusiones como las exclusiones de archivos son condiciones para el activador.

   

   • Para las inclusiones de archivos, una confirmación con cualquier cambio en runtime/src/main/a.java o cualquier archivo Java activará las canalizaciones definidas en la configuración de eventos.
   • Para las exclusiones de archivos, una confirmación con cambios solo en ambos archivos no activará las canalizaciones definidas en la configuración de eventos.
10. Haga clic en Nueva configuración.
    1. Para un evento de Gerrit, seleccione Conjunto de revisiones creado, Borrador publicado o Cambio combinado. O bien, para una inserción directa en Git que omita Gerrit, seleccione Inserción de Git directa.
       Nota: A partir de la versión 2.15 de Gerrit, ya no se admiten los cambios de borrador ni los conjuntos de cambios de borrador. Por lo tanto, si ejecuta la versión 2.15 o posterior de Gerrit, el evento Borrador publicado no se admite.
    2. Seleccione la canalización que se activará.
       Si la canalización incluye parámetros de entrada personalizados agregados, la lista Parámetros de entrada muestra parámetros y valores. Puede introducir valores para los parámetros de entrada que se transferirán a la canalización con el evento activador. Opcionalmente, puede dejar los valores en blanco o utilizar los valores predeterminados.

       Nota: Si se van a definir valores predeterminados:

       • Cualquier valor que introduzca para los parámetros de entrada sobrescribirán los valores predeterminados que se hayan definido en el modelo de canalización.
       • Los valores predeterminados en la configuración del activador no cambiarán si cambian los valores de parámetros en el modelo de canalización.

       Para obtener información sobre los parámetros de entrada de inserción automática de los activadores de Gerrit, consulte Requisitos previos.

    3. Para las opciones Conjunto de revisiones creado, Borrador publicado y Cambio combinado, algunas acciones aparecen con etiquetas de forma predeterminada. Puede cambiar la etiqueta o añadir comentarios. A continuación, cuando se ejecuta la canalización, la etiqueta o el comentario aparecen en la pestaña Actividad como la Acción realizada para la canalización.
       La configuración de eventos de Gerrit permite introducir comentarios mediante una variable para el comentario Completado correctamente o el comentario Error. Por ejemplo: ${var.success} y ${var.failure}.
    4. Haga clic en Guardar.
    Para agregar varios eventos de activador en diversas canalizaciones, vuelva a hacer clic en Nueva configuración.
    En el siguiente ejemplo, puede ver eventos de tres canalizaciones:

    • Si se produce un evento de Cambio combinado en el proyecto de Gerrit, se activará la canalización Gerrit-Pipeline.
    • Si se produce un evento de Conjunto de revisiones creado en el proyecto de Gerrit, se activarán las canalizaciones Gerrit-Trigger-Pipeline y Gerrit-Demo-Pipeline.

    

11. Haga clic en Crear.
    El activador de Gerrit aparece como una tarjeta nueva en la pestaña Activadores y está establecido en Deshabilitado de forma predeterminada.
12. En la tarjeta del activador, haga clic en Habilitar.
    Después de habilitar el activador, este puede utilizar el agente de escucha de Gerrit para empezar a supervisar los eventos que se producen en la rama del proyecto de Gerrit.
    Para crear un activador que tenga las mismas condiciones de inclusión o exclusión de archivos, pero con un repositorio diferente al que incluyó cuando creó el activador, haga clic en Acciones > Clonar. A continuación, en el activador clonado, haga clic en Abrir y cambie los parámetros.

Resultados

Enhorabuena. Configuró correctamente un activador de Gerrit con dos eventos en tres canalizaciones diferentes.

Qué hacer a continuación

Después de confirmar un cambio de código en el proyecto de Gerrit, consulte la pestaña Actividad del evento de Gerrit en Code Stream. Compruebe que la lista de actividades incluye entradas que corresponden a cada ejecución de la canalización en la configuración del activador.

Cuando se produce un evento, solo se pueden ejecutar las canalizaciones del activador de Gerrit que se relacionan con el tipo específico de evento. En este ejemplo, si se crea un conjunto de revisiones, solo se ejecutarán las canalizaciones Gerrit-Trigger-Pipeline y Gerrit-Demo-Pipeline.

La información de las columnas de la pestaña Actividad describe cada evento del activador de Gerrit. Para seleccionar las columnas que se muestran, haga clic en el icono de columna que aparece debajo de la tabla.

• Si el activador era una inserción de Git directa, las columnas Cambiar asunto y Ejecución están vacías.
• La columna Activador para Gerrit muestra el activador que creó el evento.
• La columna Agente de escucha está desactivada de forma predeterminada. Al seleccionarla, la columna muestra el agente de escucha de Gerrit que recibió el evento. Un solo agente de escucha puede aparecer como asociado a varios activadores.
• La columna Tipo de activador está desactivada de forma predeterminada. Al seleccionarla, la columna muestra el tipo de activador como AUTOMÁTICO o MANUAL.
• Otras columnas incluyen Hora de confirmación, N.° cambio, Estado, Mensaje, Acción realizada, Usuario, Proyecto de Gerrit, Rama y Evento.

Para controlar la actividad de una ejecución de la canalización completada o con errores, haga clic en los tres puntos situados a la izquierda de cualquier entrada de la pantalla Actividad.

• Si la canalización no se ejecuta debido a un error en el modelo de canalización u otro problema, corrija el error y seleccione Volver a ejecutar para volver a ejecutarla.
• Si la canalización no se ejecuta debido a un problema de conectividad de red o de otro tipo, seleccione Reanudar para reiniciar la misma ejecución de la canalización y ahorrar tiempo.
• Utilice Ver ejecución, que abre la vista de ejecución de la canalización. Consulte Cómo ejecutar una canalización y ver los resultados.
• Utilice Eliminar para eliminar la entrada de la pantalla Actividad.

Si un evento de Gerrit no activa una canalización, puede hacer clic en Activar manualmente, luego, seleccionar el activador para Gerrit, introducir el identificador de cambio y hacer clic en Ejecutar.

Nota: Activar manualmente solo funciona para eventos de Gerrit válidos, como Conjunto de revisiones creado, Cambio combinado y Borrador publicado.