Inicio rápido para GitLab Continuous Integration
Bienvenido a la guía de inicio rápido de GitLab CI, donde se le guiará a través del proceso de configurar un proyecto en GitLab y crear una configuración CI simple en código. Esta guía le permitirá iniciar rápidamente su viaje con GitLab CI.
Las siguientes tareas se describirán en esta guía de inicio rápido:
- Establecer un nuevo proyecto.
- Crear su configuración CI/CD inicial y ejecutar el pipeline.
- Acceder y revisar los resultados de la ejecución.
- Introducir condiciones basadas en reglas para determinar ejecuciones de trabajos.
- Aprovechar el poder de las plantillas de pipeline para integración perfecta de configuraciones beneficiosas.
Antes de comenzar
Asegúrese de tener una cuenta de GitLab. Si no tiene una, regístrese aquí.
Dentro de un proyecto, se gestionan varios componentes como su base de código, configuración CI, planificación, análisis y miembros del equipo. En esta guía, crearemos un nuevo proyecto con una pizarra en blanco, que contiene solo un archivo readme.
- Cree un nuevo proyecto haciendo clic en el ícono más en el lado derecho de la barra superior, y seleccionando Nuevo proyecto/repositorio
- Seleccione Crear proyecto en blanco. Bajo
Nombre del proyecto
escriba my-project. - Haga clic en Crear proyecto.
- ¡Felicitaciones! ha creado exitosamente su primer proyecto.
En GitLab, la configuración CI se define en código usando sintaxis YAML. Esta configuración especifica instrucciones a la máquina runner sobre ejecución de trabajos, orden de trabajos, condiciones de trabajos y más. Para definir la configuración CI, necesita crear un archivo llamado .gitlab-ci.yml, que debe ubicarse en la raíz de su repositorio. En esta guía, utilizaremos el IDE Web para crear y editar este archivo.
Para acceder al IDE Web, simplemente haga clic en el botón rápido del IDE Web ubicado en su proyecto. Una vez dentro del IDE Web, navegue al explorador de archivos en el lado izquierdo. Haga clic derecho dentro del explorador de archivos y elija la opción Nuevo archivo. Nombre el archivo recién creado .gitlab-ci.yml.
El orden de ejecución de trabajos está determinado por las etapas definidas en la configuración. En esta guía, definiremos tres etapas: build, test y package, en ese orden específico. Copie y pegue el siguiente código en el archivo .gitlab-ci.yml:
stages:
- build
- test
- package
Imagine un escenario donde tiene la tarea de crear dos archivos de texto. Es de suma importancia que la concatenación de estos archivos incluya la frase "Hello world." Nuestro objetivo es construir, probar y empaquetar este requisito utilizando trabajos de pipeline.
Especificaremos un trabajo de construcción que logre las siguientes tareas: crear un archivo de texto con la palabra "Hello", crear otro archivo de texto con la palabra "World", y generar un tercer archivo que almacene el contenido combinado de los dos archivos. Guardaremos el tercer archivo como un artefacto, para que los trabajos posteriores en las etapas de prueba y empaquetado puedan acceder a él. Inserte el código proporcionado debajo del bloque de etapas:
build-job:
stage: build
script:
- echo "Hello " | tr -d "\n" > file1.txt
- echo "world" > file2.txt
- cat file1.txt file2.txt > compiled.txt
artifacts:
paths:
- compiled.txt
Para validar la integridad de nuestra construcción, incorporaremos un trabajo de prueba. Este trabajo examinará si el archivo compiled.txt efectivamente contiene la frase esperada "Hello world". Inserte el siguiente código debajo del trabajo de construcción:
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world '
Tras la finalización exitosa de la prueba, nuestro siguiente objetivo es generar un paquete para nuestro código. Para lograr esto, incluiremos un trabajo de empaquetado. Es importante notar que si la prueba falla, todo el pipeline será considerado no exitoso y no procederá. Inserte el código proporcionado debajo del trabajo de prueba:
package:
stage: package
script: cat compiled.txt | gzip > packaged.gz
artifacts:
paths:
- packaged.gz
stages: # Lista de etapas para trabajos, y su orden de ejecución
- build
- test
- package
build-job:
stage: build
script:
- echo "Hello " | tr -d "\n" > file1.txt
- echo "world" > file2.txt
- cat file1.txt file2.txt > compiled.txt
artifacts:
paths:
- compiled.txt
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world'
package:
stage: package
script: cat compiled.txt | gzip > packaged.gz
artifacts:
paths:
- packaged.gz
Aquí hay un enlace al archivo de configuración en nuestro proyecto de ejemplo.
¡¡Felicitaciones!! construyó su primer pipeline CI.
Para activar la integración continua (CI) dentro de nuestro proyecto, debemos enviar el archivo .gitlab-ci.yml al repositorio. Una vez que este archivo esté ubicado en la raíz del repositorio, cada commit hecho al proyecto iniciará automáticamente un pipeline CI. El pipeline inicial comenzará inmediatamente después de enviar este archivo al servidor.
- Haga clic en el ícono Merge ubicado a la izquierda del explorador de archivos.
- Proporcione un mensaje de commit como "Adding CI configuration."
- Haga clic en Commit & Push.
- Cuando se le pregunte "¿Commit to a new branch?" seleccione "No, Use the current branch main".
- Para regresar a su proyecto, haga clic en el botón Go to project situado en el lado inferior izquierdo.
¡Felicitaciones! Su proyecto ahora está configurado exitosamente para iniciar automáticamente un pipeline CI para cada commit de código.
Mientras el pipeline está ejecutándose, puede monitorear su estado en la pestaña CI/CD. Esta característica le permite rastrear fácilmente el progreso de sus trabajos, incluyendo su estado de ejecución (como si han comenzado, pasado, fallado, etc.), así como cualquier salida generada por sus scripts de trabajo.
- Navegue al proyecto GitLab y localice el menú izquierdo.
- Haga clic en CI/CD en el menú, haga clic en Pipelines.
- En la página Pipelines, localice el botón del pipeline en la columna Status. Haga clic en él para abrir el gráfico del pipeline.
- Ahora, puede observar los trabajos y sus respectivos estados dentro del gráfico del pipeline.
- Para explorar un trabajo específico, haga clic en él para abrir la consola del trabajo. Esta consola muestra todos los pasos ejecutados en la máquina Runner.
- Abra la consola del trabajo de empaquetado para ver los pasos que fueron procesados por el runner.
- El trabajo de empaquetado genera un artefacto, puede descargarlo haciendo clic en el botón download ubicado en el lado derecho.
- Siguiendo estos pasos, puede rastrear efectivamente el estado del pipeline, inspeccionar detalles del trabajo y recuperar cualquier artefacto o paquete relevante producido durante la ejecución del pipeline.
Felicitaciones por ejecutar exitosamente su primer pipeline. ¡El pipeline tuvo éxito! Ahora ha visto los resultados y descargado el artefacto del trabajo.
Cambiaremos el valor esperado en el trabajo de prueba, el trabajo de prueba fallará así como todo el pipeline fallará.
- Edite el trabajo test modificando la frase "Hello World" a "hello world" (con letras minúsculas).
- Confirme los cambios de código y proceda a ver el pipeline, similar al Paso 4.
- Al inspeccionar el pipeline, observará que el trabajo de prueba ha fallado. Adicionalmente, el trabajo package subsecuente no comenzó, y el pipeline mismo falló como se esperaba.
En el paso 5 vimos que la falla del trabajo falló todo el pipeline. Puede introducir lógica en su pipeline que determine cuándo una falla de trabajo causará que todo el pipeline falle con los siguientes pasos:
- Evalúe las condiciones bajo las cuales quiere que una falla de trabajo resulte en falla del pipeline. Por ejemplo, puede querer forzar la falla del pipeline si un trabajo falla en la rama main o por defecto, mientras permite que las fallas de trabajo en otras ramas procedan con el pipeline.
- Defina reglas que gobiernen el comportamiento de falla. Puede aprovechar variables como $CI_COMMIT_BRANCH para verificar la rama actual y tomar decisiones basadas en ella.
- Establezca las condiciones apropiadas y especifique si el trabajo debe marcarse como allow_failure: false o allow_failure: true.
- Agregue condiciones rules/if a su trabajo de prueba.
- Use la palabra clave allow_failure establecida en true o false basada en la rama.
test:
stage: test
script: cat compiled.txt | grep -q 'Hello world'
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
allow_failure: false
- if: $CI_COMMIT_BRANCH
allow_failure: true
Para optimizar la configuración del pipeline, puede aprovechar las plantillas de pipeline integradas proporcionadas por GitLab. Estas plantillas ofrecen configuraciones predefinidas para casos de uso comunes, como escaneos de seguridad, implementaciones de aws, etc.
Siga estos pasos para utilizar las plantillas de pipeline integradas:
- Explore las plantillas de pipeline disponibles ofrecidas por GitLab para varios escenarios como construcción, pruebas, implementación y más. Estas plantillas se pueden encontrar aquí.
- Seleccione la plantilla que se alinee con sus requisitos.
- Incorpore la plantilla en su configuración de pipeline referenciándola en su archivo .gitlab-ci.yml. Típicamente puede hacer esto importando la plantilla usando la palabra clave include y especificando la ruta o URL al archivo de plantilla.
En esta guía agregaremos escaneo de calidad de código a nuestra configuración usando la plantilla de pipeline Quality.
Incorpore la plantilla de calidad de código a su .gitlab-ci.yml agregando este código debajo del bloque de etapas.
include:
- template: Jobs/Code-Quality.gitlab-ci.yml
Confirma y envía este cambio.
Notará que se agregó un trabajo de calidad de código a su pipeline. El escáner de calidad de código analizará exhaustivamente cualquier cambio de código committed a este repositorio, y proporcionará feedback valioso, resaltando cualquier problema de calidad de código que requiera atención y mejora. Este valioso insight le permite mejorar la calidad general de su base de código y optimizar su rendimiento.
¡Eso es! Con estos pasos, debería poder empezar con GitLab CI y automatizar los procesos de construcción y pruebas de su proyecto.