Generador de configuración de GitLab CI
Elige una plantilla y da forma a tu pipeline con un formulario: etapas, una imagen predeterminada, una caché basada en el archivo de bloqueo y jobs con scripts, artefactos, informes JUnit, needs y rules. El .gitlab-ci.yml se actualiza mientras escribes y se revisa en busca de errores comunes, como etapas desconocidas o needs rotos.
Última actualización:
.gitlab-ci.yml
Cómo usar Generador de configuración de GitLab CI
- Elige una plantilla, como Node.js, Python o imagen Docker, para empezar con jobs razonables.
- Configura lo básico del pipeline: la lista de etapas, la imagen predeterminada, la caché y las variables globales.
- Edita los jobs: nombre, etapa, líneas de script y cuándo se ejecutan. Abre Más opciones para services, needs, informes y entornos.
- Añade, duplica, reordena o elimina jobs y observa cómo se actualizan la vista general de etapas y el YAML.
- Corrige las notas en rojo y luego copia o descarga el archivo y haz commit como .gitlab-ci.yml en la raíz del repositorio.
Palabras clave principales de .gitlab-ci.yml
| Palabra clave | Qué hace | Ejemplo |
|---|---|---|
stages | Orden en que se ejecutan los grupos de jobs | [test, build, deploy] |
default | Ajustes que heredan todos los jobs, como image, cache e interruptible | image: node:20-alpine |
variables | Variables de entorno para todos los jobs o para uno | PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" |
script | Comandos de shell que ejecuta el job (obligatorio) | - npm test |
before_script | Comandos que se ejecutan antes de script, en el mismo shell | - docker login … |
services | Contenedores adicionales disponibles durante el job | postgres:16, docker:27-dind |
cache | Archivos reutilizados entre pipelines para ahorrar tiempo de descarga | key: {files: [package-lock.json]} |
artifacts | Resultados del job que se pasan a jobs posteriores y se conservan para descargar | paths: [dist/], expire_in: 1 week |
needs | Empezar en cuanto terminen estos jobs, sin respetar el orden de etapas | needs: [build] |
rules | Decide si un job se añade a un pipeline y cómo | - if: $CI_COMMIT_TAG |
environment | Registra los despliegues en un entorno | name: production |
workflow | Reglas que deciden si se crea el pipeline completo | Evitar pipelines duplicados de MR y de rama |
Variables CI/CD predefinidas útiles
| Variable | Valor |
|---|---|
$CI_DEFAULT_BRANCH | La rama predeterminada del proyecto, normalmente main |
$CI_COMMIT_BRANCH | Nombre de la rama en pipelines de rama (no se define en pipelines de merge request ni de tag) |
$CI_COMMIT_TAG | Nombre del tag, solo en pipelines de tag |
$CI_PIPELINE_SOURCE | Qué inició el pipeline: push, merge_request_event, schedule, web… |
$CI_COMMIT_REF_SLUG | Nombre de rama o tag adaptado para URL y claves de caché |
$CI_COMMIT_SHORT_SHA | Primeros 8 caracteres del SHA del commit, práctico como tag de imagen |
$CI_PROJECT_DIR | Ruta completa donde se clona el repositorio en el job |
$CI_REGISTRY_IMAGE | Dirección de la imagen en el registro de contenedores del proyecto |
Consejos para pipelines más rápidos y seguros
- Fija las versiones de las imágenes (
node:20-alpine, nonode:latest) para que una nueva versión upstream no rompa un pipeline de la noche a la mañana. - Usa
needspara que los jobs independientes se ejecuten en paralelo en lugar de esperar a etapas completas. - Da a los artefactos un
expire_inpara que los resultados de compilaciones antiguas no llenen tu cuota de almacenamiento. - Publica los resultados de pruebas con
artifacts:reports:junitpara ver los fallos directamente en las merge requests. - Deja los jobs de despliegue en la rama predeterminada y haz los despliegues a producción
manualhasta que confíes en el pipeline.
Preguntas frecuentes
¿Dónde pongo el archivo .gitlab-ci.yml?
Haz commit en la raíz de tu repositorio con exactamente ese nombre. GitLab lo detecta en el siguiente push e inicia un pipeline con los runners compartidos o del proyecto disponibles. Puedes previsualizarlo y validarlo en GitLab en Build, Pipeline editor.
¿Qué diferencia hay entre stages y needs?
Las etapas se ejecutan en orden: cada job de una etapa espera hasta que terminan todos los jobs de la etapa anterior. needs permite que un job empiece en cuanto terminan los jobs concretos que indica, aunque otros jobs de etapas anteriores sigan ejecutándose, lo que acorta los pipelines. Un job solo puede necesitar jobs de la misma etapa o de una anterior.
¿En qué se diferencia la caché de los artefactos?
La caché acelera los jobs reutilizando dependencias descargadas, como .npm o .m2, entre pipelines, pero no está garantizada y puede faltar. Los artefactos son los resultados de un job, como una carpeta dist o un informe de pruebas, se pasan de forma fiable a los jobs posteriores del mismo pipeline y se conservan para descargarlos hasta que caducan.
¿Por qué usar cache:key:files con un archivo de bloqueo?
Con key: files, GitLab genera la clave de caché a partir del contenido de los archivos indicados, como package-lock.json. La caché se reutiliza hasta que cambian las dependencias, y cuando cambian se crea automáticamente una nueva. Puedes indicar hasta dos archivos.
¿Qué hacen las reglas de workflow?
Sin ellas, hacer push a una rama que tiene una merge request abierta puede iniciar dos pipelines: uno de rama y otro de merge request. Las reglas de workflow generadas ejecutan los pipelines de merge request, omiten los pipelines de rama mientras haya una merge request abierta y siguen ejecutando pipelines para otras ramas y tags.
¿Cómo uso secretos en el pipeline?
No escribas contraseñas ni tokens en .gitlab-ci.yml. Añádelos en GitLab en Settings, CI/CD, Variables, márcalos como masked y protected, y úsalos en los scripts como $MY_TOKEN. Las variables predefinidas como $CI_REGISTRY_USER y $CI_REGISTRY_PASSWORD se proporcionan automáticamente para el registro de contenedores del proyecto.
¿Por qué un job necesita un script?
Todo job normal debe tener una sección script con al menos un comando; de lo contrario, GitLab rechaza la configuración. Las únicas excepciones son los jobs trigger que inician otro pipeline. Los jobs ocultos cuyo nombre empieza por un punto son plantillas para extends y no se ejecutan.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.