glab ci lint: Validate GitLab CI YAML

glab ci lint sends your .gitlab-ci.yml to GitLab's server-side CI Lint API and reports whether it is valid, including the resolved config after includes.

GitLab CI syntax is validated by the server, so a local YAML linter is not enough. glab ci lint uses the same CI Lint API the pipeline editor uses, catching include and rules errors before you push.

What it does

glab ci lint reads .gitlab-ci.yml (or a path you give it), posts it to the project CI Lint endpoint, and prints whether the config is valid plus any errors and warnings. With --dry-run it simulates a pipeline for a ref so you see the jobs that would be created.

Common usage

Terminal

glab ci lint                       # lint .gitlab-ci.yml in the repo
glab ci lint path/to/.gitlab-ci.yml
glab ci lint --dry-run             # simulate the pipeline for the default branch
glab ci config compile             # print the fully merged config

Options

Flag / command	What it does
glab ci lint [path]	Validate a CI config file (defaults to .gitlab-ci.yml)
--dry-run	Simulate creating a pipeline and list the jobs
--ref <ref>	Ref to use when simulating includes and rules
glab ci config compile	Output the merged config after includes/extends
-R, --repo <owner/repo>	Target a specific project

In CI

Run glab ci lint in a job (or the merge-request pipeline) so a broken .gitlab-ci.yml fails fast with a clear message instead of the whole pipeline erroring on load. It needs a GITLAB_TOKEN with API access.

Common errors in CI

Invalid config returns messages such as jobs:test:script config should be a string or a nested array of strings, Included file ... does not have valid YAML syntax and root config contains unknown keys: stage. Authentication problems surface as 401 Unauthorized; run glab auth login or set GITLAB_TOKEN. command not found: glab means the GitLab CLI is not installed.