Validate .gitlab-ci.yml syntax with the CI Lint tool

If you want to test the validity of your GitLab CI/CD configuration before committing the changes, you can use the CI Lint tool. This tool checks for syntax and logical errors by default, and can simulate pipeline creation to try to find more complicated issues as well.

To access the CI Lint tool, navigate to CI/CD > Pipelines or CI/CD > Jobs in your project and click CI lint.

If you use VS Code, you can also validate your CI/CD configuration with the GitLab Workflow VS Code extension.

Validate basic logic and syntax

By default, the CI lint checks the syntax of your CI YAML configuration and also runs some basic logical validations. Configuration added with the includes keyword, is also validated.

To use the CI lint, paste a complete CI configuration (.gitlab-ci.yml for example) into the text box and click Validate:

CI Lint

Pipeline simulation

Introduced in GitLab 13.3.

Not all pipeline configuration issues can be found by the basic CI lint validation. You can simulate the creation of a pipeline for deeper validation that can discover more complicated issues.

To validate the configuration by running a pipeline simulation:

  1. Paste the GitLab CI configuration to verify into the text box.
  2. Select the Simulate pipeline creation for the default branch checkbox.
  3. Select Validate.

Dry run

Pipeline simulation limitations

Simulations run as git push events against the default branch. You must have permissions to create pipelines on this branch to validate with a simulation.