Saltar al contenido

Validador de GitLab CI · CI/CD

Validar gitlab-ci.yml online, antes de que falle el runner.

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.

Se ejecuta en tu navegador: nada de lo que pegas sale de esta página. Cómo lo demostramos

Se ejecuta en tu navegador Sin registro Enfocado en la estructura Actualizado el 29 jul 2026

Playground del validador de GitLab CI

.gitlab-ci.yml

Runs entirely in your browser — nothing is uploaded.

Tip: press Esc to release keyboard focus from the editor.

Results

Load an example or paste a pipeline, then validate to see YAML errors and pipeline checks here.

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.

Consulta la lista completa en las comprobaciones del pipeline, o prueba el playground en vivo de arriba.

El pipeline

Cómo funciona.

Cinco pasos deterministas se ejecutan de principio a fin en cada validación — todos dentro de la pestaña de tu navegador, cada vez.

  1. 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ó.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Abrir el Actions Validator Abrir el Expression Tester
.gitlab-ci.yml 
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.

Más en CI/CD

Leer más sobre esto

¿Empiezas con Docker?  Lee la guía de Docker →

Browse All Tools Back to OpsCanopy

39 herramientas gratuitas, todas pueden funcionar sin conexión — opscanopy.com funciona sin registro y sin subir nada.

Herramientas relacionadas: el GitHub Actions Validator y el GitHub Actions Expression Tester. Explora el directorio completo de herramientas.

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.