La automatización de tareas documentales es esencial en entornos DevOps, donde el flujo de trabajo continuo y la trazabilidad son cruciales para el desarrollo ágil. En esta publicación, exploraremos un script diseñado para integrarse en los pipelines de CI/CD de GitLab, que automatiza la creación de un archivo que lista todos los repositorios relacionados con una Historia de Usuario. Este archivo documenta cada referencia en diferentes repositorios y adjunta el archivo resultante al WorkItem en Azure DevOps.
Contexto. ¿Por qué creamos esta automatización?
En la entrega y despliegue continuo de software hacia ambientes de pruebas (QA, UAT) o producción (Staging, PROD), es esencial tener un registro de todos los servicios creados o modificados que deben ser empaquetados para evitar fallas, como la falta de algoritmos, endpoints o configuraciones. Este control asegura que cada elemento necesario esté presente en el despliegue, minimizando riesgos en la entrega final del software.
En un enfoque en cascada, la creación de documentación detallada en cada fase del proceso, como Checklists de instalación, es común para guiar despliegues manuales. Sin embargo, en un entorno que adopta DevOps, estos documentos manuales son incompatibles con la filosofía de despliegues automáticos. La alternativa ideal en DevOps es automatizar la generación de estos documentos directamente desde los repositorios de código, vinculándolos con las Historias de Usuario para mejorar la eficiencia sin perder control. El resultado del proceso descrito en este artículo es un archivo atachado a la Historia de Usuario con información de los repositorios que deben ser desplegados y sus responsables.
Automatizando la generación de documentación para despliegues
Implementamos un algoritmo en Python que se ejecuta como un job dentro de los pipelines de CI/CD en GitLab. Un job es parte de un stage, y varios stages conforman un pipeline. Cada job contiene instrucciones específicas para ejecutar análisis de seguridad, pruebas de regresión, compilación, despliegue del software, etc. Creamos un stage exclusivo para integraciones con Azure DevOps llamado «azure», que incluye el job «azure-attach-repository-lists-to-hu». Este job ejecuta el script para generar documentos de despliegue.
Al realizar el merge entre las ramas de desarrollo y QA, GitLab ejecuta el pipeline de la rama de destino. Al llegar al job de generación de documentación de despliegue, se activa un script de automatización que, mediante librerías de Python, interactúa con las APIs de Azure y GitLab para recopilar información de commits, repositorios, tableros y Work Items. El flujo a grandes rasgos es el siguiente:
- Busca los IDs de los WorkItems de Azure en los mensajes de commits. Para esto, los mensajes deben estar estandarizados.
- Estándar: se utiliza Conventional Commits con una ligera variación para especificar la historia de usuario.
- Formato: <type>(<scope>): HU(<WorkItemID#1>, <WorkItemID#N>) <mensaje>
- Ejemplo: feat(core): HU(12345) Nuevo endpoint de consulta
- El algoritmo extrae los valores que están dentro de «HU()», en este caso «12345».
- Busca información de los WorkItem IDs encontrados en los mensajes, para esto usa la API de Azure.
- Verifica que el ID exista, busca el proyecto o tablero al que pertenece, etc.
- Con la API de Gitlab, se itera en paralelo sobre los repositorios buscando los commits que hacen referencia al WorkItem ID y se obtiene su metadata (repositorio, fecha , responsable, etc). Recomendaciones:
- No es factible buscar en todos los repositorios de la institución, se recomienda tener una lista blanca de repositorios autorizados para cada célula, por ejemplo: microservicios, fuses, lambdas, etc.
- Tampoco se recomienda buscar los commits desde el principio de los tiempos, en su lugar, se define una configuración para buscar commits desde hace 3 o 4 meses según la duración de los proyectos.
- Es indispensable configurar las ramas de búsqueda, por ejemplo, si estoy desplegando en QA, entonces buscaré los commits asociados al WorkItem en repositorios que ya están en QA y los repositorios de ramas previas, por ejemplo DEV.
- Finalmente, consolida esta información en un archivo de texto con toda la información de despliegue y, mediante la API de Azure, adjunta este archivo al WorkItem del tablero.
Implementación. ¿Cómo se configuran los pipelines de GitLab?
El job se configura en las plantillas YAML de los repositorios. Para no configurar el archivo de despliegue en todos los proyectos, se sigue el proceso de centralización de plantillas (proceso que se detalla en este post) el cual es importado en todos los proyectos a manera de herencia.
Para conseguir este comportamiento, requerimos de un repositorio central de templates YAML, será el repositorio padre. Aquí definimos la configuración YAML del stage que usaremos para nuestro proceso, lo llamamos: «microservice/stages/BA-Stage-Azure-Attach-Repository-Lists-To-HU.yml«.
azure-attach-repository-lists-to-hu:
tags: [LaboratorioDigital01]
stage: azure
image: $GITLAB_IMAGEN_LOCAL/python-azure-gitlab-automation:3.12 # Imagen que ejecuta la tarea
rules:
- if: $CI_COMMIT_BRANCH == "qa" # Condición de ejecución
when: always
script:
- echo "$CI_COMMIT_REF_NAME"
- echo "$CI_COMMIT_SHA"
- echo "$CI_PROJECT_ID"
- MODE="execution"
- GITLAB_TOKEN={GITLAB TOKEN} # Token de consumo de API para Gitlab
- AZURE_TOKEN={AZURE TOKEN} # Token de consumo de API para Azure
- python3 ./cicd-azure/automation-repo-commit-catalog.py -1 "$CI_COMMIT_SHA" -2 "$CI_COMMIT_REF_NAME" -3 "$CI_PROJECT_ID" -4 "$GITLAB_TOKEN" -5 "$AZURE_TOKEN" -6 "$MODE"
Considerar que este stage se ejecuta sobre una imagen docker con Linux que tiene instalada la versión 3.12 de Python (sección «image»). En la parte final de la configuración anterior podemos ver cómo se llama al script que ejecuta la tarea de generación de documento de despliegue (sección «script»). Los parámetros que recibe como entrada son:
- CI_COMMIT_SHA: SHA del commit que se está integrando en el repositorio.
- CI_COMMIT_REF_NAME: Rama en donde se está integrando la nueva funcionalidad.
- CI_PROJECT_ID: ID del repositorio de GitLab en donde se está realizando el CI/CD.
- GITLAB_TOKEN: Token para consumo de la API de GitLab.
- AZURE_TOKEN: Token para consumo de la API de Azure.
- MODE: Modo de ejecución (pruebas o producción)
Ahora, la configuración anterior tiene que ser incluida en el YAML general de nuestro repositorio padre, este último es usado por todos los servicios que «heredan» las funcionalidades centralizadas. El YAML en cuestión es «microservice/BA-AWS-Microservice.yml«.
include:
- local: 'stages/BA-Stage-Aws-Build-Image.yml'
- local: 'stages/BA-Stage-Release.yml'
- local: 'stages/BA-Stage-Regression-Test.yml'
- local: 'stages/BA-Stage-Azure-Create-Production-Pbi.yml'
- local: 'stages/BA-Stage-Azure-Attach-Repository-Lists-To-HU.yml'
Finalmente, este YAML se incluye en los archivos de despliegue de todos los repositorios que se desea sean parte del proceso de automatización: microservicios, fuses, lambdas, etc., en donde se requiere heredar esta funcionalidad centralizada. Por ejemplo, así se vería parte del YAML del microservicio Core-Semaphore para incluir el template definido en el paso anterior:
image: $GITLAB_IMAGEN_LOCAL/docker:20.10.16
include:
- project: 'laboratoriodigital/devops/ci-cd-templates/microservice'
ref: main
file: '/BA-AWS-Microservice.yml'
De esta manera, se deja el camino listo para que en el próximo pase a QA se ejecute el JOB que genera la documentación automática de despliegue analizando los Work Items y su relación con los repositorios que fueron modificados o creados durante la etapa de desarrollo.
Ejecución. ¿Cómo veo los resultados?
Para ver los resultados de esta automatización tenemos dos posibilidades. La primera, encontrar la ejecución del job en los pipelines del repositorio. Por ejemplo:
Los logs de ejecución del job ofrecen un resumen del proceso ejecutado con los repositorios involucrados en este despliegue. A continuación un ejemplo:
Sin embargo, el verdadero valor de esta automatización radica en que el archivo generado se adjunta directamente al Work Item (Historia de Usuario, Bug, etc.) en Azure DevOps, proporcionando visibilidad al equipo de desarrollo, QA y Product Owners que monitorean constantemente el estado y progreso de los Work Items en los tableros durante un Sprint.
El archivo generado contiene un resumen de los repositorios modificados, creados o actualizados durante el desarrollo del Work Item, junto con los commits, fechas y responsables de cada cambio. Esto facilita una visión clara de los servicios necesarios para la instalación en los distintos entornos al entregar una Historia de Usuario. La versión inicial del documento es la siguiente:
Conclusión
La automatización en pipelines de CI/CD es esencial en la cultura DevOps, ya que minimiza el trabajo manual, reduce errores y permite a los equipos enfocarse en crear valor a través del software. Este enfoque permite generar documentos de despliegue automáticamente a partir de la información de los repositorios y commits diarios, integrando estos archivos en las Historias de Usuario para involucrar a todos los miembros del equipo en el proceso DevOps. A futuro, se busca mejorar el formato de los documentos y añadir datos adicionales relevantes a los repositorios de cada Work Item, según las necesidades del equipo.
