Skip to content

GitLab CI Validator · CI/CD

A GitLab CI validator that catches mistakes before the runner does.

This GitLab CI validator lets you paste a .gitlab-ci.yml and get its YAML errors plus the structural misconfigurations GitLab would reject — undefined stages, jobs with no script, broken needs/extends. Validate your .gitlab-ci.yml instantly, right in your browser. No install, no project, no login.

Runs in your browser — nothing you paste leaves this page. How we prove that

Runs in your browser No signup Structure-focused Updated Jul 29, 2026

GitLab CI Validator playground

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

The Gap

Valid YAML is only half the job.

A .gitlab-ci.yml can parse as perfectly good YAML and still be a broken pipeline. The mistakes that actually fail a run are structural: a job pointing at a stage you never declared, a job with no script, a needs entry naming a job that does not exist, or an extends on a template you renamed.

GitLab’s own pipeline editor and CI Lint catch these — but only after you push to a project and sign in. This .gitlab-ci.yml checker runs the same high-signal structural checks before you commit, entirely in your browser, against GitLab’s .gitlab-ci.yml keyword reference. It is a GitLab CI linter you can run with no install — and it never asks you to create a project or log in.

It checks both — the YAML and the pipeline structure — so you can validate your GitLab CI pipeline before push, with nothing to install and nothing uploaded. Paste your .gitlab-ci.yml and validate online in seconds, the same way you would in a hosted GitLab CI lint, but offline and private.

See the full list in the pipeline checks, or try the live playground above.

The Pipeline

How this gitlab-ci.yml validator works online.

Five deterministic steps run end-to-end on every validation — a full GitLab CI YAML lint in the browser, no install and no project, every time.

  1. Parse the YAML.

    Your .gitlab-ci.yml is parsed with a YAML reader — syntax errors, bad indentation, and structural problems (like GitLab CI’s "did not find expected key" error) are reported with the line that broke.

  2. Split the config.

    The top level is split into global keywords (stages, default, variables…), visible jobs, and hidden .templates, so the analyser knows what is a job and what is configuration.

  3. Resolve the stages.

    The declared stages: list (or the five defaults: .pre, build, test, deploy, .post) becomes the set every job stage is checked against.

  4. Check every job.

    This is the needs / rules / stages validation pass: each job is checked for an executable surface, a known stage, real needs / extends / dependencies targets, a valid when, a list-shaped rules, and sane image / services shapes.

  5. Rank by severity.

    Findings are graded error, warning, or info — the pipeline-breaking mistakes rise to the top, ahead of advisory notes like legacy only/except, each with a concrete fix.

Pipeline Checks

What this GitLab CI config validator checks.

Beyond YAML validity, this GitLab pipeline validator looks for the misconfigurations that fail a pipeline before a single job runs — so you can check your .gitlab-ci.yml for errors online before you push. Each of the 4 checks below shows the broken pattern and the fix.

Stage not declared in stages:

High severity

A job whose stage: is not in your stages: list (or one of the defaults .pre, build, test, deploy, .post) is a configuration error — GitLab does not know when to run it and refuses the pipeline.

Broken

.gitlab-ci.yml
# BROKEN — "release" is not a declared stage
stages:
  - build
  - test

release-job:
  stage: release       # not in stages:
  script:
    - make release

Fixed

.gitlab-ci.yml
# FIXED — every stage used is declared
stages:
  - build
  - test
  - release

release-job:
  stage: release
  script:
    - make release

GitLab CI job without script error

High severity

A visible job must do something: run commands (script:/run:), start a downstream pipeline (trigger:), or inherit those from another job (extends:). A job with none of them triggers the GitLab CI "job without script" error and is rejected.

Broken

job
# BROKEN — this job does nothing
build-job:
  stage: build
  # no script, run, trigger, or extends

Fixed

job
# FIXED — give the job a script
build-job:
  stage: build
  script:
    - make build

needs / extends pointing at a missing job

Medium severity

Every entry in needs:, dependencies:, or extends: must reference a job or hidden .template that actually exists in the file. A reference to a missing job breaks the pipeline graph.

Broken

.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

Fixed

.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

Invalid when: / non-list rules:

Medium severity

when: only accepts on_success, on_failure, always, manual, delayed, or never. rules: must be a YAML list of rule objects — a mapping or a typo here changes (or breaks) when a job runs.

Broken

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

Fixed

job
# FIXED — valid when, rules as a list
deploy:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_TAG'
      when: manual
  script: ./deploy.sh

Stages, rules and job dependencies are all documented in GitLab’s stages reference and rules reference. Legacy only/except and image/services shape checks also run today. As a .gitlab-ci.yml validator online, every one of these runs as a GitLab CI lint online in your browser — a GitLab CI validator online with no install and no project required.

Next Step

Run GitHub Actions too? Validate those workflows.

Many teams run pipelines on both platforms. Once your .gitlab-ci.yml is clean, the GitHub Actions Validator finds the YAML errors and security holes in your workflows, and the GitHub Actions Expression Tester evaluates ${{ … }} expressions before you push — both entirely in your browser.

.gitlab-ci.yml
stages: [build, test]

build:
  stage: build
  script: make

test:
  stage: test
  needs: [build]   # ✓ resolves
  script: make test

FAQ

Questions, answered.

Tap a question to expand the answer.

Paste the pipeline YAML into a browser-based GitLab CI validator to catch errors before you commit — no install and no push needed. This tool runs the full check set (YAML structure plus pipeline misconfigurations) entirely in your browser, so you get instant feedback on syntax errors, undefined stages, jobs without scripts, broken needs/extends, and invalid when values before the config ever reaches a GitLab runner. Paste your .gitlab-ci.yml and validate online to get a clear pass or fail with the line and reason for each problem.

Yes. GitLab’s built-in CI Lint requires a project and a sign-in, but this validator does not. You can validate a .gitlab-ci.yml without a project, an account, or a login — just paste the YAML and the GitLab CI linter runs 100% in your browser. Nothing is uploaded to a server, so you can safely check internal or proprietary pipelines, including ones with private runner tags and secret variable references.

That message means GitLab rejected your pipeline before running it — almost always because of a structural mistake rather than bad YAML. The usual causes are a job with no script / run / trigger / extends, a job whose stage is not in your stages list, needs or extends pointing at a job that does not exist, an invalid when value, or a rules block that is not a list. To fix "this GitLab CI configuration is invalid", paste your .gitlab-ci.yml here: the validator runs the same high-signal checks and tells you exactly which job and key broke, with the fix.

Run a GitLab CI YAML lint in the browser before you commit. Paste the config into this validator and it checks both the YAML and the pipeline structure — undefined stages, jobs without scripts, broken needs/extends, invalid when — so you can validate a GitLab CI pipeline before push. A clean result here is strong pre-push confidence; for absolute certainty, confirm with GitLab’s own CI Lint, which also resolves includes and project variables.

Yes. This is a free GitLab CI YAML validator with no signup, no install, and no login. It runs entirely client-side in your browser, so there is no account to create and nothing to upload. Paste your .gitlab-ci.yml and validate online instantly — the tool is free to use as often as you like.

Two things at once. First, it parses your .gitlab-ci.yml and reports YAML syntax errors, bad indentation, and structural mistakes (such as the "did not find expected key" error) with the line that broke. Second, it runs needs / rules / stages validation that matches how GitLab itself validates a config: a job with no script / run / trigger / extends, a job whose stage is not in your stages list, needs and extends references that point at jobs that do not exist, an invalid when value, a rules block that is not a list, legacy only/except, and bad image/services shapes. You get YAML errors and pipeline mistakes in one pass.

The GitLab CI "did not find expected key" error is a YAML problem, not a pipeline-logic one — it almost always comes from inconsistent indentation, a missing colon, or mixing tabs and spaces, so the parser expected a mapping key and found something else. Paste your .gitlab-ci.yml into this validator: it reports the exact line where the YAML structure broke so you can re-indent or add the missing key and re-validate.

A GitLab job has to do something. A regular job runs commands with script: (or the newer run:), a bridge job starts a downstream pipeline with trigger:, and a job can inherit any of those from another job or hidden template via extends:. A visible job that defines none of them produces the GitLab CI "job without script" error — GitLab rejects it with a message like "job config should implement a script: or a trigger: keyword". This validator flags any visible job missing all four. Hidden templates (keys starting with a dot) are allowed to be partial fragments, so they are not required to have a script.

More free, private DevOps tools.

The GitLab CI Validator is one tool in OpsCanopy — a growing canopy of browser-based validators, converters and testers that never touch a server.

New to Docker?  Read the Docker guide →

39 free tools, every one offline-capable — opscanopy.com works with no signup and nothing uploaded.

Related tools: the GitHub Actions Validator and the GitHub Actions Expression Tester. Browse the full tools directory.

Not affiliated with, endorsed by, or sponsored by GitLab B.V. GitLab is a trademark of GitLab B.V., used here only descriptively to identify the .gitlab-ci.yml pipeline format this tool checks.