Cómo configurar pipelines de Integración Continua (CI) de GitLab en Ubuntu 20.04

Cada desarrollador entiende lo crucial que es el control de versiones para el ciclo de vida del desarrollo de software. Permite que varias personas trabajen simultáneamente en un solo proyecto, manteniendo cada una su propia copia del código y eligiendo cuándo compartirla con el resto del equipo. Para lograr esto, los desarrolladores hacen uso de Git repositorios para ayudar con el control de versiones. GitLab es un repositorio Git basado en la web que es más que una herramienta de control de versiones. Además, proporciona herramientas de DevOps, seguimiento de problemas, integración continua y despliegue.

GitLab ofrece tres opciones entre las que puede elegir: GitLab Community Edition (CE), GitLab Enterprise Edition (EE) y GitLab SaaS. GitLab CE y GitLab EE son soluciones autogestionadas. Esto significa que usted mismo descarga, instala y gestiona la instancia de GitLab. GitLab SaaS está alojado por GitLab Inc. Por lo tanto, no tiene que preocuparse por instalar nada para usarlo. Solo necesita crear una cuenta de GitLab y comenzar.

En este tutorial, le mostraremos cómo configurar canalizaciones de Integración Continua con GitLab CI para monitorear sus repositorios en busca de cambios y ejecutar pruebas automatizadas para validar el nuevo código. Comenzaremos configurando un repositorio Git para alojar el código. Luego, configuraremos un proceso de CI para monitorear las confirmaciones (commits) en el repositorio e iniciaremos un CI runner para ejecutar las pruebas en un contenedor Docker aislado.

Requisitos previos

Para comenzar, necesitará un servidor que ejecute el software de control de versiones GitLab. Tanto GitLab autogestionado como SaaS pueden ejecutar pruebas automatizadas. Sin embargo, existen algunos límites en cuanto a los minutos y recursos disponibles para sus pruebas en las opciones gratuitas de SaaS. Tiene más libertad si utiliza las opciones autogestionadas porque puede asignar tantos recursos como desee a su instancia de GitLab. Siga nuestro tutorial sobre cómo alojar sus propios repositorios Git con GitLab para aprender cómo configurar su propia instancia de GitLab.

Necesitará al menos un servidor para usarlo como GitLab CI runner. Sin embargo, si lo desea, también puede tener más servidores. Si ha configurado una instancia de GitLab autogestionada, puede usar el mismo servidor, pero preferimos configurar un servidor diferente para el CI runner. Este tutorial sobre Cómo configurar su servidor Ubuntu es un buen comienzo.

Necesitará tener Docker instalado en sus servidores de GitLab CI runner para aislar los entornos de prueba en contenedores Docker. Tenemos un tutorial sobre Cómo instalar y operar Docker en Ubuntu que puede ayudarle a completar este requisito.

Ahora que tenemos todo lo que necesitamos, ¡comencemos!

Paso 1: Crear un proyecto en una instancia de GitLab

Comenzaremos creando un repositorio de proyecto en GitLab. Vamos a basar este tutorial en una aplicación Node.js. Dado que no queremos crear los archivos del proyecto desde cero, GitLab ofrece una herramienta para importar proyectos desde otros repositorios de control de versiones que utilizaremos. La aplicación que estamos importando es una simple aplicación “hello world” construida con Express.js – un framework web minimalista para aplicaciones Node.js. Implementaremos las pruebas utilizando Mocha y Chai – estos son frameworks de JavaScript utilizados para pruebas unitarias. Mocha permite pruebas asíncronas, informes de cobertura de pruebas y se puede combinar con otras bibliotecas de aserciones. Chai es una biblioteca de aserciones. Se puede combinar con cualquier framework de prueba; en nuestro caso, combinaremos Mocha con Chai.

Ahora que conoce los conceptos básicos de nuestro proyecto, inicie sesión en su instancia de GitLab (ya sea autogestionada o SaaS), haga clic en el icono ‘más’ en la barra de navegación superior y seleccione ‘Nuevo proyecto’. Opcionalmente, si se desplaza a la parte superior de la página de inicio de su cuenta, puede hacer clic en el botón ‘Nuevo proyecto’:

En la página de nuevo proyecto, haga clic en la pestaña Importar proyecto :

A continuación, en la página abierta, haga clic en el botón Repo por URL :

Aunque existe una opción de importación de GitHub, no la vamos a utilizar ya que requiere un token de acceso personal (Personal access token). No necesitamos configurar tokens de acceso personal ya que estamos trabajando con un repositorio público, y la importación solo con la URL es sencilla.

Después de eso, copia la siguiente URL y pégala en el campo Git Repository URL:

Debería verse así:

Deja el repositorio como Privado y haz clic en el botón Create project cuando hayas terminado. Espera un par de segundos a que el proyecto se importe desde GitHub y aparecerá entre tus repositorios de GitLab. GitLab importa el proyecto con los mismos detalles que el proyecto del repositorio de GitHub.

Paso 2: Análisis del archivo .gitlab-ci.yml

GitLab CI escanea cada repositorio en GitLab en busca de un archivo llamado .gitlab-ci.yml para saber cómo debe ejecutar las pruebas automatizadas. En el repositorio que acabamos de importar, puedes ver un .gitlab-ci.yml entre los archivos del proyecto. Puedes encontrar más información sobre el yml de GitLab CI en su documentación oficial de referencia de palabras clave para el archivo .gitlab-ci.yml.

Mientras estás en la interfaz del repositorio de GitLab, haz clic en el archivo .gitlab-ci.yml para abrirlo en la página del navegador. Debería verse así:

Ten en cuenta la sangría de las líneas. El archivo sigue una estricta GitLab CI YAML sintaxis de configuración para definir las diversas acciones que se deben realizar, en un orden especificado bajo ciertas condiciones. Para garantizar que tus archivos de configuración sean correctos, GitLab proporciona una utilidad de prueba para la validación. Dentro de tu instancia de GitLab, en el repositorio de tu proyecto, puedes visitar la interfaz de CI lint para validar tu .gitlab-ci.yml. Haz clic en CI/CD en el menú de navegación de la izquierda, y haz clic en el botón CI lint en la página que aparece:

Las directivas en el archivo de configuración se analizan a continuación.

• Imagen Docker base

La primera línea del archivo de configuración declara una imagen de Docker que debe usarse para ejecutar las pruebas. Dado que estamos construyendo una aplicación Node.js, optaremos por la última imagen de Node.js:

• Etapas

Luego, definimos las diferentes etapas por las que queremos que pasen nuestras pruebas de integración continua. Solo tenemos dos etapas:

Al definir los nombres de las etapas, los nombres como build o test se eligen al azar – puedes elegir cualquier nombre que desees. Sin embargo, debes ordenar las etapas correctamente porque eso determina el flujo de ejecución. En nuestro caso, los trabajos en la etapa build se ejecutan antes que los trabajos en la etapa test . GitLab Runner ejecutará los trabajos de la misma etapa en paralelo y esperará a que se completen todos los trabajos antes de comenzar a ejecutar los trabajos de la siguiente etapa.

• Caché

Se incluye una definición de cache para especificar los archivos y directorios que se almacenarán en caché o se guardarán para su uso posterior entre las ejecuciones de los trabajos:

Definir el almacenamiento en caché ayuda a minimizar el tiempo necesario para ejecutar trabajos que dependen de recursos que es poco probable que cambien entre ejecuciones. Especificamos que se almacene en caché el directorio node_modules. Este es el directorio en el que npm instala las dependencias del proyecto.

• Trabajos

Tenemos dos trabajos en la configuración:

• install_dependencies

Al nombrar los trabajos, eres libre de elegir cualquier nombre. Sin embargo, se recomienda elegir un nombre descriptivo, ya que se utilizan en la interfaz de usuario de GitLab – esto puede ser útil durante la depuración. Encontrarás la mayoría de las configuraciones en la web combinando npm install con los comandos en la etapa de prueba. Solo los separamos para ayudar a demostrar cómo interactúan los trabajos, ya que este es un proyecto bastante pequeño. La stage directive marca este trabajo como build – se ejecuta en la etapa build.

La script especifica los comandos a ejecutar en la ejecución de este trabajo. Puedes especificar múltiples comandos agregando líneas dentro del bloque script. Por supuesto, debes tener cuidado de indentar correctamente y tener en cuenta el orden en que se deben ejecutar los scripts.

La artifacts especifica las rutas de archivos o directorios para guardar y compartir entre etapas. Nuevamente, un recordatorio de que ordenar las etapas correctamente es crucial para garantizar que otros archivos tengan lo que necesitan para ejecutarse. El comando npm install instalará las dependencias en el directorio node_modules. Al declararlo en los artifacts, lo ponemos a disposición de los trabajos ejecutados en las etapas posteriores. Los archivos también están disponibles en la interfaz de usuario de GitLab si deseas descargarlos.

• test_with_mocha

Este trabajo se ejecuta en la etapa test. Dado que este trabajo se ejecuta después de que se haya ejecutado el trabajo en la etapa build, los artefactos declarados en la etapa build (que son las dependencias de nuestra aplicación) estarán disponibles para la etapa test. El bloque script especifica los comandos npm para ejecutar nuestras pruebas. Primero iniciamos nuestra aplicación y luego ejecutamos las pruebas contra la aplicación. Al ejecutar estos comandos se activan los comandos especificados en la sección del bloque de script de package.json:
Con eso, deberías tener una comprensión básica del archivo .gitlab-ci.yml. Decimos básica porque esta es solo una aplicación estática hello world. A continuación, veamos cómo podemos activar una nueva ejecución de CI.

Paso 3: Activar una ejecución de GitLab CI

Te alegrará saber que una vez que tu repositorio tenga el archivo .gitlab-ci.yml, cualquier nuevo commit que envíes activará una nueva ejecución de Integración Continua. En el caso de las instancias de GitLab autogestionadas, si no has configurado un GitLab runner, la ejecución de CI se establecerá en “pendiente”.

GitLab SaaS ofrece a los usuarios algunos runners compartidos que pueden tomar sus trabajos y ejecutarlos automáticamente. Esto solo es posible si los runners compartidos están libres y no has superado tu cuota. En GitLab SaaS, puedes elegir si deseas que tu repositorio use los runners compartidos o no yendo a la página Settings > CI / CD de tu proyecto, como se muestra en la captura de pantalla a continuación. En esta página, también encontrarás información sobre las instrucciones de instalación del GitLab runner, en las que profundizaremos en el siguiente paso:

Ahora, hagamos un pequeño cambio para activar una ejecución de CI. Navega de regreso al repositorio de tu proyecto de GitLab node_pipeline:

Haz clic en el archivo README.md resaltado anteriormente para verlo:

Haz clic en el botón ‘Edit’ para abrir el archivo para editarlo en el navegador y agrega algo de texto:

Una vez que hayas agregado algo de texto, desplázate hacia abajo y haz clic en el botón Commit changes para guardar los cambios. Puedes modificar el mensaje de commit como desees. Aparecerá como un título en la interfaz de usuario de GitLab cuando la pipeline se esté ejecutando. Lo hemos dejado como Update README.md ya que es bastante descriptivo:

Una vez que hayas realizado el commit de los cambios, regresa a la página principal del proyecto. Notarás un pequeño icono de pausa junto al commit más reciente. Si pasas el cursor del ratón sobre el icono, se mostrará: ‘Pipeline:pending’:

Esto significa que se activó la ejecución de CI. Sin embargo, las pruebas aún no se han ejecutado. En el menú de navegación de la izquierda, haz clic en CI/CD, luego selecciona Pipelines. Esto abrirá una página que muestra más detalles sobre la pipeline. Puedes ver que la CI está pendiente y marcada como atascada:

Para obtener más detalles sobre la ejecución, haz clic en el estado pending. Verás la vista a continuación, que muestra las diferentes etapas de la ejecución y los trabajos individuales vinculados a cada etapa:

También puede hacer clic en trabajos individuales para ver sus detalles más específicos, como qué está causando los retrasos. En el caso de ejecuciones fallidas, aquí es donde verá qué causó que el trabajo fallara:

El mensaje indica que el trabajo está atascado porque no ha configurado ningún ejecutor activo que pueda ejecutar este trabajo. Haremos eso en el siguiente paso. Cuando ponga a disposición un ejecutor, el trabajo comenzará a ejecutarse automáticamente. Cuando se ejecuta un trabajo, verá la salida en esta interfaz, así como los otros artefactos descargables generados cuando el trabajo se estaba ejecutando.

Paso 4: Configuración de un servicio de GitLab CI Runner

Ahora es el momento de hacer uso del segundo servidor que declaramos en la sección de Requisitos previos de este tutorial. Instalaremos y configuraremos un servicio de GitLab runner en este servidor. Puede implementar el servicio para ejecutar múltiples instancias de ejecutor para diferentes proyectos en GitLab.

Tiene la opción de implementar el ejecutor en el mismo servidor que aloja su instancia autogestionada de GitLab. Sin embargo, para garantizar que una instancia no se vea limitada por los recursos, es preferible configurar una instancia de CI runner separada. Cualquiera que sea la configuración que elija, Docker debe estar instalado para aislar los entornos de prueba.

El proceso para instalar el GitLab CI runner es comparable al de instalar la instancia autogestionada de GitLab de GitLab. Comenzamos descargando un script para agregar el repositorio oficial de GitLab a las fuentes de apt usando el siguiente comando:

Proporcione su contraseña de root cuando se le solicite. A continuación, ahora puede ejecutar el comando para instalar el último GitLab CI runner:

El comando anterior instala y registra un servicio de ejecutor listo para ser utilizado por sus proyectos.

Paso 5: Obtención de tokens de registro y vinculación del GitLab Runner

Para configurar un GitLab CI runner para que comience a aceptar trabajos, necesita un token de GitLab runner. Es necesario para que el ejecutor se autentique con su instancia de servidor de GitLab. Hay dos tipos de tokens según cómo desee utilizar el ejecutor: específico del proyecto y ejecutor compartido.

Los ejecutores específicos del proyecto son aplicables si tiene requisitos únicos para el ejecutor. Por ejemplo, si tiene definiciones de implementación en su gitlab-ci.yml con tokens únicos, entonces se puede recomendar un ejecutor específico para autenticarse correctamente en el entorno de implementación. Otra consideración es si sus etapas de integración continua tienen procesos que consumen muchos recursos. Entonces, lo ideal sería optar por un ejecutor específico del proyecto. Tenga en cuenta que un ejecutor específico del proyecto no acepta trabajos de otros proyectos.

Los ejecutores compartidos son de propósito general y pueden ser utilizados por múltiples proyectos. La instancia de GitLab SaaS alojada en GitLab Inc tiene algunos ejecutores compartidos que seleccionarán automáticamente sus canalizaciones como se explica en el Paso tres. Los ejecutores toman trabajos de sus configuraciones basándose en un algoritmo que tiene en cuenta la cantidad de trabajos que se están ejecutando actualmente para cada proyecto. Un ejecutor compartido es más flexible que un ejecutor específico. Se puede configurar desde la cuenta de administrador de la instancia de GitLab. Veamos cómo podemos obtener los tokens para ambos ejecutores.

• Registro de un ejecutor específico del proyecto

Para registrar un ejecutor específico del proyecto, abra su proyecto en su instancia de GitLab o cuenta de GitLab SaaS. En el menú de navegación de la izquierda, haga clic en el elemento Configuración y seleccione la opción CI/CD:

Después de eso, desplácese hacia abajo hasta la sección Runners y haga clic en el botón para expandir la sección:

El lado izquierdo explica cómo registrar un ejecutor específico del proyecto. Esta es una vista de la instancia de GitLab SaaS. También puede configurar ejecutores automáticos con Kubernetes, pero para este tutorial realizaremos la configuración del ejecutor manual:

A continuación, debe centrarse en la sección donde se le proporciona el token para este proyecto. Para una instancia de GitLab autogestionada, la URL mostrará el dominio del servidor en el que se está ejecutando su instancia de GitLab:

Puede optar por desactivar los runners compartidos para este proyecto cambiando el interruptor en la sección de la derecha bajo Runners compartidos. Luego, copie el token de registro que se muestra en su bloc de notas, ya que lo usaremos más adelante.

• Registrar un Runner compartido

Para registrar un runner compartido, debe iniciar sesión en su instancia de GitLab autogestionada como administrador. Para acceder al panel de administración, haga clic en el llave inglesa en el menú de navegación superior:

En el Panel de administración, haga clic en Runners en la sección Información general del menú de la izquierda. Esto abrirá una página con las instrucciones de configuración de Runners compartidos:

Copie el token de registro que se muestra en el lado derecho bajo Configurar un Runner compartido manualmente. Utilizará el token para registrar el runner en el siguiente paso.

• Vincular un GitLab CI Runner con una instancia de GitLab

En este paso, vinculará su instancia de GitLab con el runner de CI. Vuelva a iniciar sesión en el servidor donde instaló el servicio de GitLab runner en el Paso cuatro. Para iniciar el proceso de registro del runner, introduzca el siguiente comando en su terminal:

El comando le hará una serie de preguntas:

• Introduzca la URL de la instancia de GitLab (por ejemplo, https://gitlab.com/):

Proporcione el nombre de dominio de su instancia de GitLab utilizando https:// para especificar SSL.

• Introduzca el token de registro:

Proporcione su token de registro. Aquí es donde elegirá si desea que este runner sea específico del proyecto o compartido. Solo puede proporcionar uno de los tokens que copió anteriormente para cualquiera de las opciones.

• Introduzca una descripción para el runner:

Elija un nombre descriptivo para su runner de CI, ya que aparecerá en la interfaz de usuario de la instancia de GitLab.

• Introduzca un ejecutor: custom, docker-ssh, parallels, virtualbox, docker, shell, ssh, docker+machine, docker-ssh+machine, kubernetes:

Aquí se le proporcionan opciones para elegir un ejecutor para ejecutar los trabajos. Introduzca Docker.

• Introduzca etiquetas para el runner (separadas por comas):

Esto es opcional. Puede introducir cualquier nombre de etiqueta, como las dependencias que incluye este runner. Puede dejarlo en blanco por ahora.

• Introduzca la imagen de Docker predeterminada (por ejemplo, ruby:2.6):

Aquí se espera que especifique una imagen predeterminada de propósito general utilizada para ejecutar trabajos en caso de que el archivo gitlab-ci.yml no especifique una imagen. Introduzca alpine:latest ya que es una imagen pequeña, de propósito general y segura. Presione enter y el runner se registrará y se iniciará automáticamente:

Para ver la lista de runners disponibles actualmente, introduzca el siguiente comando:

Paso 6: Confirmación de que el CI Runner se ha vinculado correctamente en GitLab

A continuación, vuelva a su navegador y visite la página de su proyecto en la instancia de GitLab. Dependiendo de cuántos minutos hayan pasado desde que registró el runner, es posible que vea que el trabajo se está ejecutando actualmente:

O puede que se haya completado:

Después de eso, navegue a la página de Pipelines ya sea a través del menú de la izquierda CI/CD > Pipelines, o haciendo clic en el icono running, passed, o failed (si la canalización encontró errores) para ver el estado de la ejecución de CI. Aquí podemos ver que una de las etapas (etapa de compilación) se ha completado con éxito, mientras que otra aún se está ejecutando:

En la tabla, bajo el encabezado Stages, haga clic en uno de los iconos de las etapas para ver los trabajos asociados:

Luego, haga clic en un trabajo en la ventana emergente para ver los detalles:

El trabajo se ejecutó y puede ver el progreso de cuando el comando npm estaba instalando las dependencias. En el lado derecho, puede ver otra información relacionada. Tiene la opción de descargar los artefactos del trabajo. También puede cambiar entre etapas para ver otros trabajos desde el menú desplegable.

Aquí puede ver nuestros casos de prueba que se muestran al seleccionar el trabajo en la etapa de prueba:

Runners disponibles

En el menú de la izquierda, si hace clic en Configuración > CI/CD, y expande la sección Runners sección, debería ver el runner que acaba de registrar. Dependiendo de si había especificado un token específico del proyecto o un token compartido, el runner aparecerá en la sección correspondiente.

Aquí puede ver que registramos un token específico del proyecto. El runner aparece bajo Runners específicos:

Conclusión

En este tutorial, aprendió cómo puede automatizar sus pruebas con GitLab CI. Comenzamos configurando un proyecto de aplicación Node.js en GitLab. El proyecto incluía algunos casos de prueba y un gitlab-ci.yml. Aprendimos que GitLab utiliza el archivo gitlab-ci.yml para determinar qué hacer cuando se activa. Un archivo gitlab-ci.yml es solo un archivo de configuración que contiene instrucciones sobre la construcción y prueba de aplicaciones, escrito en formato YAML que un runner de GitLab CI puede entender.

También logramos configurar un runner de GitLab CI en un host separado. Lo registramos para que acepte trabajos de nuestras instancias de GitLab cada vez que haya un activador. Aunque este fue un proyecto simple, puede basarse en esta información para configurar pipelines para proyectos complejos. Los pasos para agregar un proyecto a GitLab y vincular un runner de GitLab CI siguen siendo los mismos. Lo que cambia son las instrucciones y las etapas en el archivo gitlab-ci.yml.

¡Feliz computación!