GitLab CI/CD YAML Syntax Explained

The .gitlab-ci.yml file describes the jobs that make up a GitLab pipeline. YAML structure matters: indentation uses spaces, lists use ordered entries, and duplicate or misplaced keys can change behavior or make the configuration invalid.

Global and job-level configuration#

Essential keywords#

• stages defines the ordered phase names.
• script lists the commands a job executes.
• image selects the container image for compatible executors.
• variables provides non-secret configuration values or references.
• rules controls when a job is included and how it behaves.
• needs creates explicit job dependencies and can shorten pipeline duration.
• artifacts preserves outputs and reports.
• cache reuses safe dependency data across jobs or pipelines.
• environment records deployment targets and URLs.

Stages and dependencies#

Without explicit needs relationships, jobs typically follow stage ordering. Use needs when a job can start as soon as its required upstream jobs finish. Keep dependency graphs understandable; aggressive parallelism can make failures and resource contention harder to diagnose.

Reusable configuration#

Reduce duplication with defaults, YAML anchors where appropriate, extends, and included configuration. Pin external includes to a reviewed reference. Reuse should make policy clearer, not hide important execution or permission behavior.

Validate before committing#

1. Check YAML indentation and data types.
2. Use GitLab CI Lint or pipeline-editor validation.
3. Inspect the merged configuration when includes are used.
4. Confirm rule outcomes for branches, tags, merge requests, and schedules.
5. Review resolved variables without exposing secret values.
6. Run the change on a non-production branch and trusted runner.

Common mistakes#

Treat pipeline YAML as production code: review it, validate it, test it under multiple pipeline sources, and restrict who can change deployment or security-sensitive sections.

GitLab CI/CD YAML syntax reference