GitLab CI: formatear y validar tu .gitlab-ci.yml en línea

¿Por qué revisar un .gitlab-ci.yml antes de que corra el pipeline?

Un .gitlab-ci.yml que no parsea, un stages que no es un array, o un job sin script ni trigger, suele verse demasiado tarde: badge rojo, Pipeline Editor, merge bloqueado. FastMinify no incluye el CI Lint oficial de GitLab y no ejecuta ningún runner. El validador GitLab CI hace controles estructurales en el navegador — mapping raíz, stages, jobs con script o trigger, include, jobs ocultos . — y el formateador GitLab CI reindenta el YAML (2 o 4 espacios). El cluster completo está en el hub de herramientas CI/CD. Para minificar JS/CSS en el mismo pipeline, consulta la guía de minificación CI/CD.

Detectar YAML inválido, un stages mal tipado o un job sin script/trigger antes del push

Formatear la indentación de 2 o 4 espacios para una review legible

100 % en el navegador — el archivo nunca se envía

Tope de 512 KiB UTF-8, como el resto de herramientas DevOps del sitio

Dejar GitLab CI Lint (includes remotos, rules, esquema oficial) para glab y la UI

GitLab vs GitHub Actions: dos YAML, tres capas

Un archivo raíz, no una carpeta de workflows

GitHub Actions vive en .github/workflows/*.yml (varios archivos, trigger on, jobs con steps). GitLab CI vive casi siempre en un solo .gitlab-ci.yml en la raíz: stages, jobs con nombre, include. Las herramientas FastMinify siguen esa frontera — no pegues un workflow de Actions en el validador de GitLab.

GitLab: un documento YAML, jobs en el primer nivel (salvo claves reservadas)

GitHub: mapa jobs anidado + on obligatorio — ver la guía de GitHub Actions

Dockerfile y Compose siguen en el hub DevOps

Para YAML genérico (no CI), usa beautify-yaml

Un artefacto JS minificado de un job no es YAML de CI: unminify-js

Formatear, validar, CI Lint: tres capas, no un solo botón

FastMinify expone dos herramientas. Ninguna es GitLab CI Lint. Mezclar las tres produce un archivo «válido» aquí que igual falla en Pipeline Editor.

Formatear: round-trip js-yaml, indentación 2 o 4 espacios (por defecto 2) — ver format-gitlab-ci

Validar: parse YAML + estructura (mapping, stages, jobs, include) — ver validate-gitlab-ci

GitLab CI Lint: esquema oficial, expansión de include, evaluación de rules: — UI Pipeline Editor, API o glab ci lint

Los comentarios YAML se eliminan al formatear (el mismo límite que beautify-yaml) — guarda una copia si dependes de ellos

Un veredicto «estructura OK» no prueba que un include remoto exista ni que una cláusula rules: seleccione el job

Lo que FastMinify no simula

El validador no habla con el runner de GitLab, no llama a la API CI Lint y no expande includes remotos. Las menciones de rules: son un tema real de GitLab — no una función del navegador.

Sin ejecución de script, sin imagen Docker, sin caché del runner

Sin expansión de include: remote / include: project — solo se lee el YAML pegado

Sin evaluación de rules:, only/except ni workflow:rules

Los jobs pages son jobs como los demás: necesitan script o trigger

El filtro esquema + includes + rules sigue siendo GitLab CI Lint, no FastMinify

Anatomía de un .gitlab-ci.yml: lo que FastMinify comprueba

La forma mínima de una config GitLab CI

La raíz debe ser un mapping YAML, no un escalar ni una lista. Un solo documento: los --- repetidos se rechazan. Si stages está presente, debe ser un array de nombres no vacíos. Cada clave que no esté reservada y no empiece por . es un job: necesita script (cadena o lista no vacía) o trigger.

Claves reservadas (no son jobs): stages, variables, include, workflow, default, image, services, cache, before_script, after_script, spec

Jobs ocultos / plantillas .hidden: sin requisito de script

Job solo con extends: aviso — el padre debe aportar script o trigger

Ningún job y ningún include de primer nivel: aviso, no siempre un bloqueo

El panel cuenta jobs, stages e includes tras un parse correcto

Formatear: round-trip js-yaml, comentarios perdidos

El formateador hace pretty-print con js-yaml. No es un reescritor semántico: el orden de las claves puede cambiar, los comentarios # desaparecen, la indentación pasa a 2 o 4 espacios.

Antes

stages: [test]
unit:
 stage: test
 script: [npm test]

Después

stages:
  - test
unit:
  stage: test
  script:
    - npm test

Pegar, subir o sample: formato automático; tras una edición manual, botón Formatear (⌘↵)

Indentación 2 o 4 espacios (por defecto 2) — dump js-yaml, no Prettier

Los comentarios no se conservan — cópialos antes si el archivo depende de ellos

Encadena format → validate para una review legible y una estructura sana

YAML fuera de GitLab CI: beautify-yaml

include, rules y el tope de 512 KiB

Un include de primer nivel basta para evitar el aviso «ningún job». FastMinify no descarga los archivos incluidos. Por encima de 512 KiB UTF-8, la entrada se rechaza — como el resto de herramientas DevOps del sitio.

Contador de include: un escalar cuenta 1; un array cuenta su longitud

Los includes remotos siguen opacos — CI Lint de GitLab los fusiona, el navegador no

Las rules: del YAML pegado no se interpretan

Entrada vacía: estado inactivo, no «inválido»

Un documento demasiado grande: usa glab ci lint en local

Validar y luego formatear: un flujo concreto

Usar el validador GitLab CI

Abre el validador GitLab CI, pega un solo .gitlab-ci.yml (máx. 512 KiB) y espera el debounce (~300 ms). El panel muestra un veredicto, los issues (error de parse con pista de línea) y contadores de jobs / stages / includes.

Controles: mapping raíz, stages array, jobs con script o trigger, include, jobs ocultos .

Sin runner, sin esquema CI Lint, sin expansión remota de include/rules

Solo extends: aviso; job sin script ni trigger: error

Todo queda local — sin cuenta, sin upload a un servidor FastMinify

Formatear el YAML antes del merge request

El formateador GitLab CI hace pretty-print con js-yaml. Pegar, subir o sample: formato automático; tras una edición manual, usa el botón Formatear. Este paso no prueba que la estructura esté completa.

Alinear una plantilla de job o un recorte de docs mal indentado

Los comentarios # desaparecen en el round-trip — cópialos antes si los necesitas

Encadena format → validate para una review legible y una estructura sana

Para YAML fuera de GitLab CI, usa beautify-yaml en lugar de esta herramienta

Escenario — job sin script ni trigger

Un compañero añadió compile: solo con stage: build. GitLab rechaza el pipeline, a menudo con un mensaje poco legible en el overlay del MR.

Paso 1: pegar el archivo en validate-gitlab-ci

Abre validate-gitlab-ci. Un veredicto inválido del tipo «Job … needs script or trigger» apunta al job vacío.

Paso 2: añadir script o trigger

Añade script: [npm run build] o un trigger: real. Vuelve a pegar hasta que el panel muestre una estructura válida (los avisos de extends pueden quedar).

Paso 3: formatear y abrir el MR

Pasa el YAML corregido por format-gitlab-ci, copia, haz commit. Los reviewers leen jobs indentados, no un blob.

Escenario — YAML pegado de un ticket, indentación rota

Un ejemplo copiado de la doc de GitLab o un snippet llega con espacios mezclados. Ya no ves dónde termina un job.

Paso 1: formatear primero si el archivo es ilegible

Pega en format-gitlab-ci. Este paso no prueba que la config esté estructuralmente completa.

Paso 2: validar el documento indentado

Copia la salida al validador. Revisa stages, cada job, y que las plantillas . no oculten un job visible roto.

Paso 3: dejar CI Lint para includes y rules

Cuando la forma esté OK, el filtro esquema / includes remotos / rules: sigue en GitLab — FastMinify no lo sustituye.

Mantener GitLab CI Lint (y minify) en la cadena

glab ci lint — la red de esquema antes del push

El navegador es el bucle rápido: YAML + estructura. GitLab ya rechaza crear un pipeline si el esquema oficial es inválido — por eso casi nunca se embebe un job «lint CI» en el mismo archivo. En local, glab ci lint (CLI oficial, autenticada en el proyecto) llama a CI Lint: includes fusionados, simulación opcional con --dry-run. Fija la versión de glab; FastMinify no sustituye esa llamada. Para minificar JS/CSS en el pipeline, consulta la guía de minificación CI/CD.

Ejemplo básico

# Local, before git push — official GitLab CI Lint (not FastMinify).
# Requires glab authenticated to the project.
glab ci lint .gitlab-ci.yml

# Optional: simulate pipeline creation (expands includes, uses --ref).
# glab ci lint --dry-run --ref main

GitHub Actions, DevOps, unminify

Si el repo está en GitHub, los equivalentes son format-github-actions y validate-github-actions — la misma idea (YAML + estructura, no actionlint). Dockerfile y Compose siguen en el hub DevOps. Un bundle JS minificado de un job se lee con unminify-js o la guía unminify — eso no es YAML de CI.

Conclusión

Pega el .gitlab-ci.yml, corrige la estructura (mapping, stages, jobs con script/trigger), reindenta y haz push. FastMinify hace ese bucle en local y no envía el YAML. No es GitLab CI Lint: includes remotos, rules: y el esquema oficial siguen en la UI, la API o glab ci lint. Para YAML genérico, quédate en beautify-yaml; para GitHub Actions, en el mismo hub CI/CD.

Valida o formatea un .gitlab-ci.yml ahora

Valida la estructura antes de cada MR que toque .gitlab-ci.yml

Formatea para la review, pero espera perder los comentarios YAML

No trates un veredicto FastMinify como luz verde de CI Lint

Deja includes remotos y rules: en glab / Pipeline Editor

Encadena validate → format, luego glab ci lint antes del push