Integración con GitLab CI Allure 3
Allure Report 3 incluye el comando allure gitlab para jobs de GitLab CI/CD. En un job, el comando:
- genera el reporte e imprime un enlace que lo abre desde los artefactos del job;
- mantiene el historial entre pipelines, usando el archivo de historial del job anterior;
- en pipelines de merge request, publica un resumen del reporte como comentario en el merge request.
El comando solo funciona dentro de un job de GitLab CI/CD, porque lee las variables predefinidas de CI/CD del job. En cualquier otro lugar, se detiene con el error GitLab CI environment was not detected.
Generar el reporte en un pipeline
Agregue allure gitlab al job que ejecuta sus pruebas, después de las pruebas, y guarde el directorio del reporte y el archivo de historial como artefactos del job:
test:
image: node:22
script:
- npm ci
- npm test || true
- npx allure gitlab ./allure-results
artifacts:
when: always
paths:
- allure-report
- history.jsonlEste ejemplo es para un proyecto Node.js con el paquete allure en sus dependencias de desarrollo, cuyas pruebas escriben resultados en el directorio allure-results usando una integración de Allure. En un proyecto en otro lenguaje, use una imagen que tenga tanto sus herramientas como Node.js.
|| truepermite que el job llegue aallure gitlabcuando algunas pruebas fallan. Sin esto, GitLab detiene el job en el primer comando que falla. Para hacer fallar el job debido a pruebas fallidas, configure un quality gate. Cuando este falla,allure gitlabigualmente genera el reporte y publica el comentario, y luego sale con el código 1, lo que hace fallar el job.when: alwaysguarda los artefactos incluso cuando el job falla.
El comando escribe el reporte en el directorio allure-report e imprime su dirección, por ejemplo:
GitLab report URL: https://my-group.gitlab.io/-/my-project/-/jobs/1234/artifacts/allure-report/index.htmlEl enlace abre el reporte desde los artefactos del job a través de GitLab Pages, por lo que explorar artefactos debe estar disponible en su instancia de GitLab, como lo está en GitLab.com. En un proyecto privado, el lector debe iniciar sesión en GitLab para abrir el reporte. Para publicar el reporte en otro lugar, consulte --history-base-url.
Mantener el historial entre pipelines
allure gitlab mantiene el historial de resultados de prueba en el archivo history.jsonl. Antes de generar el reporte, descarga este archivo de los artefactos de la ejecución anterior del mismo job, y luego agrega los resultados de la ejecución actual. Por eso el archivo de historial debe estar en los artefactos del job.
La ejecución anterior es el job más reciente que:
- tiene el mismo nombre que el job actual;
- se ejecutó para la misma rama;
- se ejecutó en un pipeline del mismo tipo, por ejemplo, un pipeline de rama o un pipeline de merge request;
- finalizó con el estado aprobado o fallido y no fue reintentado.
Como resultado, los pipelines de merge request no usan el historial de la rama de destino, ni el de pipelines de rama de su rama de origen. Solo usan pipelines de merge request anteriores de la misma rama de origen, por lo que en el primer pipeline de un merge request, todas las pruebas son nuevas.
Si no hay una ejecución anterior, o sus artefactos no contienen el archivo de historial o han expirado, el comando imprime un error, como history fetch failed: no matching prior job in returned pipeline window, y genera el reporte sin el historial anterior. Esto nunca hace fallar el job.
En un proyecto público, el historial se descarga sin un token. En un proyecto privado, el comando necesita un token con al menos el alcance read_api. Sin él, imprime history fetch failed: invalid project en cada ejecución.
Por defecto, el historial mantiene 100 entradas. Para cambiar esto, use --history-limit. Para mantener el historial en otro archivo, use --history-path y agregue ese archivo a los artefactos en lugar de history.jsonl.
Publicar un resumen en merge requests
En pipelines de merge request, allure gitlab puede publicar un resumen del reporte como comentario en el merge request:
Haga que GitLab ejecute pipelines de merge request, por ejemplo, agregando estas reglas de la documentación de GitLab a
.gitlab-ci.yml:yamlworkflow: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS when: never - if: $CI_COMMIT_BRANCHCree un token de acceso con el alcance
apique tenga al menos el rol Reporter en el proyecto:- un token de acceso de proyecto, creado en Settings > Access tokens del proyecto (en GitLab.com, requiere el plan Premium o Ultimate);
- o un token de acceso personal de un miembro del proyecto con al menos el rol Reporter, por ejemplo, un usuario creado para este propósito.
El token del job (
CI_JOB_TOKEN) no se puede usar: el comando no puede descargar el historial ni publicar el comentario con él.En Settings > CI/CD > Variables del proyecto, guarde el token en la variable
GITLAB_TOKEN, con la visibilidad Masked.Si marca la variable como Protected, GitLab solo la pasa a pipelines de ramas protegidas, por lo que los merge requests de otras ramas no obtienen un comentario.
En lugar de la variable
GITLAB_TOKEN, puede pasar el token con la opción--gitlab-token. La opción tiene prioridad sobre la variable.

El comentario se titula Allure Report Summary. Contiene una tabla con la duración de la ejecución, el número de pruebas con cada estado, y los números de pruebas nuevas, inestables y reintentadas, que enlazan al reporte filtrado por estas pruebas. Debajo de la tabla, hay enlaces al reporte, al commit y al pipeline. El comentario no incluye los resultados del quality gate.
Si el archivo de configuración tiene varios plugins de reporte, por ejemplo, awesome y dashboard, cada reporte se genera en su propio subdirectorio del directorio del reporte, y el comentario enlaza a cada uno de ellos.
Cada job publica su propio comentario, y los pipelines posteriores del merge request lo actualizan en lugar de publicar uno nuevo. El comentario se publica en nombre del usuario del token, que es un usuario bot para un token de acceso de proyecto.
Sin un token, el comando imprime no API token provided, skipping en su lugar. En pipelines de rama, imprime failed to add summary comment: missing merge request, que puede ignorar. Para desactivar el comentario, use --no-summary-comment.
Merge requests desde forks
Por defecto, el pipeline de un merge request desde un fork se ejecuta en el fork, por lo que no puede comentar en el merge request de su proyecto: el comando imprime failed to add summary comment: cross-project merge request. Para obtener el comentario, ejecute el pipeline en su proyecto.
Combinar resultados de jobs paralelos
Cuando las pruebas se ejecutan en varios jobs, por ejemplo, con parallel, genere un reporte en un job de una etapa posterior. Para pasarle los resultados, ejecute las pruebas con allure run --dump y pase los archivos a allure gitlab con --dump:
stages: [test, report]
default:
image: node:22
test:
stage: test
parallel: 2
script:
- npm ci
- npx allure run --dump=dump-$CI_NODE_INDEX -- npx vitest run --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
artifacts:
when: always
paths:
- dump-*.zip
report:
stage: report
when: always
script:
- npm ci
- npx allure gitlab --dump "dump-*.zip"
artifacts:
when: always
paths:
- allure-report
- history.jsonlwhen: always hace que el job de reporte se ejecute incluso cuando algunos de los jobs de prueba fallan.
Alternativamente, guarde el directorio allure-results como artefacto de los jobs de prueba. GitLab extrae los artefactos de todos los jobs de prueba en el mismo directorio del job de reporte, por lo que npx allure gitlab ./allure-results lee los resultados de todos ellos.
Publicar el reporte en Allure Report Storage
Si Allure Report Storage está configurado en la sección allureService del archivo de configuración, allure gitlab publica el reporte allí, y el comentario enlaza al reporte publicado en lugar de a los artefactos del job.
El historial entonces proviene del servicio de almacenamiento, por lo que el comando no descarga ni escribe el archivo de historial, y no necesita guardarlo como artefacto. Para el historial de pipelines de merge request, consulte Profundidad del historial y ramas.
Opciones del comando
npx allure gitlab [options] [<results directories>...]El comando lee los resultados de los directorios que coincidan con las rutas o patrones dados. Sin ellos, usa resultsDir del archivo de configuración, o todos los directorios allure-results en el directorio actual y sus subdirectorios.
| Opción | Descripción |
|---|---|
--config, -c | La ruta al archivo de configuración. |
--output, -o | El directorio del reporte. Por defecto: allure-report. Una ruta absoluta debe estar dentro del directorio del proyecto (CI_PROJECT_DIR). |
--report-name, --name | El nombre del reporte. Por defecto: name del archivo de configuración, o Allure Report. |
--history-path | El archivo de historial. Por defecto: history.jsonl. |
--history-limit | El número máximo de entradas de historial a mantener. Por defecto: 100. |
--history-base-url | La dirección pública del directorio del reporte, si usted mismo lo publica. Los enlaces al reporte en el comentario y en el historial entonces apuntan allí. Por defecto: la dirección del reporte en los artefactos del job. |
--dump | La ruta o patrón de archivos creados por allure run --dump. Se puede especificar varias veces. |
--summary-comment, --no-summary-comment | Si publicar el comentario de resumen en pipelines de merge request. Por defecto: activado. |
--gitlab-token | El token para descargar el historial y publicar el comentario. Por defecto: el valor de la variable de entorno GITLAB_TOKEN. |
El directorio del reporte, el archivo de historial, el límite del historial y la dirección pública del reporte solo se pueden establecer con estas opciones: allure gitlab ignora las opciones output, historyPath, historyLimit y historyBaseUrl del archivo de configuración. Las demás opciones del archivo de configuración, como plugins y qualityGate, se aplican como de costumbre.