GitLab CI Validator:
Validar gitlab-ci.yml online, antes de que falle el runner.
Se ejecuta en tu navegador: nada de lo que pegas sale de esta página. Cómo lo demostramos
Playground del validador de GitLab CI
Example
.gitlab-ci.yml
stages:
- build
- test
- deploy
default:
image: node:20
build-job:
stage: build
script:
- npm ci
- npm run build
test-job:
stage: test
needs:
- build-job
script:
- npm test
deploy-job:
stage: deploy
needs:
- test-job
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
script:
- ./deploy.sh
Results update as you type — press ⌘/Ctrl + Enter to run now. Press Esc to release the editor.
fig. 23 — gitlab-ci-validator · ci/cdNo issues
Results
No issues found.
This pipeline passed every YAML and structural check.
Pega un .gitlab-ci.yml para validarlo
online y obtén sus errores de YAML más las configuraciones estructurales incorrectas que GitLab
rechazaría — stages no definidos, jobs sin script, needs/extends rotos. Este linter de GitLab CI corre al instante en tu navegador. Sin instalación, sin
proyecto y sin iniciar sesión.
La brecha
Un YAML válido es solo la mitad del trabajo.
Un .gitlab-ci.yml puede analizarse
como YAML perfectamente válido y aun así ser un pipeline roto. Los errores que de verdad
hacen fallar una ejecución son estructurales:
un job apuntando a un stage que
nunca declaraste, un job sin script,
una entrada de needs que nombra un
job que no existe, o un extends sobre
una plantilla que renombraste.
El propio editor de pipelines y CI Lint de GitLab los detectan — pero solo después de que haces push a un proyecto e inicias
sesión. Este validador ejecuta las mismas comprobaciones estructurales de alta señal
antes de que hagas commit, por completo en tu navegador, contra la referencia de palabras clave de .gitlab-ci.yml de GitLab.
Comprueba ambas cosas —el YAML y la estructura del pipeline— para que puedas
comprobar tu pipeline de GitLab y validar el .gitlab-ci.yml
antes de hacer push, sin nada que instalar y sin nada que subir.
Cinco pasos deterministas se ejecutan de principio a fin en cada validación — todos dentro de la pestaña de tu navegador, cada vez.
01
Analiza el YAML.
Tu .gitlab-ci.yml se analiza con un lector de YAML: los errores de sintaxis, la indentación incorrecta y los problemas estructurales se reportan con la línea que falló.
02
Separa la config.
El nivel superior se separa en palabras clave globales (stages, default, variables…), jobs visibles y .templates ocultas, para que el analizador sepa qué es un job y qué es configuración.
03
Resuelve los stages.
La lista stages: declarada (o los cinco por defecto: .pre, build, test, deploy, .post) se convierte en el conjunto contra el que se comprueba el stage de cada job.
04
Comprueba cada job.
Cada job se valida en busca de una superficie ejecutable, un stage conocido, destinos reales de needs / extends / dependencies, un when válido, unas rules con forma de lista y formas sensatas de image / services.
05
Ordena por severidad.
Los hallazgos se gradúan como error, advertencia o info: los errores que rompen el pipeline suben a lo más alto, por delante de las notas informativas como los only/except heredados, cada uno con una solución concreta.
Comprobaciones del pipeline
Las 4 comprobaciones que importan.
Más allá de la validez del YAML, este validador de GitLab CI YAML busca las configuraciones
incorrectas que hacen fallar un pipeline antes de que se ejecute un solo job. Cada una de las
de abajo muestra el patrón roto y la solución.
Stage no declarado en stages:
Severidad alta
Un job cuyo stage: no está en tu lista stages: (o en uno de los por defecto .pre, build, test, deploy, .post) es un error de configuración: GitLab no sabe cuándo ejecutarlo y rechaza el pipeline.
Roto
.gitlab-ci.yml
# BROKEN — "release" is not a declared stage
stages:
- build
- test
release-job:
stage: release # not in stages:
script:
- make release
Corregido
.gitlab-ci.yml
# FIXED — every stage used is declared
stages:
- build
- test
- release
release-job:
stage: release
script:
- make release
Job sin script / trigger / extends
Severidad alta
Un job visible debe hacer algo: ejecutar comandos (script:/run:), iniciar un pipeline descendente (trigger:), o heredar esos de otro job (extends:). Un job sin ninguno de ellos es rechazado por GitLab.
Roto
job
# BROKEN — this job does nothing
build-job:
stage: build
# no script, run, trigger, or extends
Corregido
job
# FIXED — give the job a script
build-job:
stage: build
script:
- make build
needs / extends apuntando a un job inexistente
Severidad media
Cada entrada en needs:, dependencies: o extends: debe referenciar un job o una .template oculta que realmente exista en el archivo. Una referencia a un job inexistente rompe el grafo del pipeline.
Roto
.gitlab-ci.yml
# BROKEN — "compile" and ".base" never exist
test:
stage: test
needs:
- compile # no such job
extends: .base # no such template
script:
- make test
Corregido
.gitlab-ci.yml
# FIXED — references resolve to real definitions
.base:
image: golang:1.22
compile:
stage: build
extends: .base
script: make
test:
stage: test
needs:
- compile
extends: .base
script: make test
when: inválido / rules: que no es una lista
Severidad media
when: solo acepta on_success, on_failure, always, manual, delayed o never. rules: debe ser una lista YAML de objetos de regla: un mapping o una errata aquí cambia (o rompe) cuándo se ejecuta un job.
Roto
job
# BROKEN — bad when value, rules is a mapping
deploy:
stage: deploy
when: sometimes # not allowed
rules:
if: '$CI_COMMIT_TAG' # rules must be a list
script: ./deploy.sh
Corregido
job
# FIXED — valid when, rules as a list
deploy:
stage: deploy
rules:
- if: '$CI_COMMIT_TAG'
when: manual
script: ./deploy.sh
Los stages, las rules y las dependencias entre jobs están todos documentados en la
referencia de stages y la
referencia de rules de GitLab. Las comprobaciones de formas heredadas de only/except y de image/services también funcionan hoy.
Siguiente paso
¿También ejecutas GitHub Actions? Valida esos workflows.
Muchos equipos ejecutan pipelines en ambas plataformas. Una vez que tu
.gitlab-ci.yml esté limpio, el
GitHub Actions Validator encuentra los errores de YAML y los
agujeros de seguridad en tus workflows, y el
GitHub Actions Expression Tester evalúa las expresiones
${{ … }} antes de que hagas push —
ambos por completo en tu navegador.
stages: [build, test]
build:
stage: build
script: make
test:
stage: test
needs: [build] # ✓ resolves
script: make test
FAQ
Tus preguntas, respondidas.
Toca una pregunta para desplegar la respuesta.
¿Cómo valido un archivo .gitlab-ci.yml?
Para validar .gitlab-ci.yml online, pega el contenido del archivo en este validador y lo comprueba al instante en tu navegador. Hace dos cosas a la vez. Primero, analiza tu .gitlab-ci.yml y reporta errores de sintaxis YAML, indentación incorrecta y fallos estructurales con la línea que se rompió. Segundo, ejecuta comprobaciones de configuraciones de pipeline incorrectas que coinciden con cómo GitLab valida una config: un job sin script / run / trigger / extends, un job cuyo stage no está en tu lista de stages, referencias de needs y extends que apuntan a jobs que no existen, un valor de when inválido, un bloque rules que no es una lista, only/except heredados, y formas incorrectas de image/services. Obtienes errores de YAML y errores de pipeline en una sola pasada.
¿Puedo usar el linter de GitLab CI sin un proyecto?
Sí. A diferencia del CI Lint integrado, este linter de GitLab CI no necesita un proyecto de GitLab ni que inicies sesión. Pega tu .gitlab-ci.yml y comprueba el pipeline de GitLab al instante: todo corre del lado del cliente, dentro de la pestaña de tu navegador. No se sube nada a un servidor, así que puedes revisar con seguridad pipelines internos o propietarios, incluidos los que tienen etiquetas de runners privados, nombres de imágenes internas y referencias a variables secretas.
¿Por qué GitLab dice «this GitLab CI configuration is invalid»?
Ese mensaje significa que tu .gitlab-ci.yml es YAML que se analiza, pero infringe el esquema del pipeline en algún punto: un job sin script, un stage que no está en stages:, un valor de when no permitido, un bloque rules que no es una lista, o un needs/extends que apunta a un job que no existe. Este validador de GitLab CI YAML reproduce esas comprobaciones de alta señal y te señala la línea y la causa exacta, para que sepas qué corregir antes de volver a abrir el CI Lint de GitLab.
¿Cómo reviso los errores de mi .gitlab-ci.yml antes de hacer push?
Pega el YAML del pipeline en un validador basado en navegador para revisar errores de gitlab-ci.yml antes de hacer commit: sin instalar nada y sin necesidad de push. Esta herramienta ejecuta el conjunto completo de comprobaciones (estructura YAML más configuraciones de pipeline incorrectas) por completo en tu navegador, así que obtienes feedback instantáneo sobre errores de sintaxis, stages no definidos, jobs sin scripts, needs/extends rotos y valores de when inválidos antes de que la config llegue siquiera a un runner de GitLab.
¿Existe un validador de GitLab CI online y gratis, sin iniciar sesión?
Sí: esta es exactamente esa herramienta. Es un validador de GitLab CI gratuito que se ejecuta 100% del lado del cliente, sin cuenta, sin registro y sin proyecto. Validar .gitlab-ci.yml online aquí no envía tu configuración a ningún servidor, así que es seguro pegar pipelines privados. Trata un resultado limpio como una sólida confianza previa al push, y luego confírmalo con el CI Lint de GitLab cuando hagas merge.
¿Qué comprueba realmente el CI Lint de GitLab CI?
El editor de pipelines y el CI Lint de GitLab son autoritativos: resuelven includes, variables del proyecto y el esquema en vivo, por eso requieren un proyecto y un viaje de ida y vuelta al servidor. Este validador reproduce las comprobaciones estructurales de mayor señal sin conexión: stages no declarados, jobs sin script / run / trigger / extends, referencias rotas de needs y extends, valores de when inválidos, bloques rules que no son listas, only/except heredados y formas incorrectas de image/services. Es el control rápido que haces mientras editas, antes de pasar por el CI Lint oficial.
¿Cómo soluciono el error «did not find expected key» en GitLab CI?
Ese error de YAML casi siempre es de indentación: una clave anidada con el número equivocado de espacios, una lista a la que le falta el guion -, o tabuladores mezclados con espacios. YAML es sensible a la indentación, así que GitLab no encuentra la clave que esperaba en ese nivel. El validador te marca la línea exacta donde el lector de YAML se rompió, para que alinees la indentación o añadas el guion que falta. Revisa que cada job y cada clave global (stages, default, variables) estén al mismo nivel y que las listas usen guiones consistentes.
¿Por qué mi job de GitLab CI falla con «job has no script»?
Un job visible de GitLab tiene que hacer algo: ejecutar comandos con script: (o el más reciente run:), iniciar un pipeline descendente con trigger:, o heredar cualquiera de esos de otro job o plantilla oculta mediante extends:. Un job que no define ninguno de los cuatro es rechazado con un error como «job config should implement a script: or a trigger: keyword». El validador señala cualquier job visible al que le falten los cuatro; la solución es darle un script: o un extends: a una plantilla que sí lo tenga. Las plantillas ocultas (claves que empiezan por un punto) pueden ser fragmentos parciales, así que no se les exige tener un script.
More free, private DevOps tools.
El GitLab CI Validator es una herramienta dentro de
OpsCanopy — una creciente cubierta de validadores, conversores y
probadores basados en navegador que nunca tocan un servidor.
No está afiliado, respaldado ni patrocinado por GitLab B.V.GitLab es una marca comercial de GitLab B.V.,
usada aquí solo de forma descriptiva para identificar el formato de pipeline .gitlab-ci.yml
que esta herramienta comprueba.