GitLab CI/CD Pipeline File Structure
You'll learn how GitLab parses your .gitlab-ci.yml file and the essential structure that makes pipelines work.
How GitLab Reads Your Pipeline
When you commit a .gitlab-ci.yml file, GitLab's parser reads it like a blueprint. It scans for specific top-level keywords that define what to run, when to run it, and how jobs relate to each other. Think of it as a recipe where GitLab needs ingredients (jobs), cooking steps (scripts), and timing instructions (stages) in a format it recognizes.
Core Structure Elements
Your .gitlab-ci.yml is a YAML document with several key sections:
Top-level keywords control pipeline-wide settings:
stages:- defines the execution order (like chapters in a book)variables:- sets global environment variablesdefault:- applies common settings to all jobs
Job definitions are named blocks that specify work to be done. Each job must have:
script:- the actual commands to executestage:- which stage it belongs to (optional, defaults to "test")
Optional job keywords refine behavior:
image:- Docker image to useartifacts:- files to preservecache:- dependencies to speed up runsrules:- conditions for execution
Parsing Logic
GitLab reads your file linearly but executes jobs by stage order. It validates syntax first—one typo breaks the entire pipeline. Jobs without a stage go into the default "test" stage. Hidden jobs (prefixed with .) aren't executed but can be templates for other jobs.
Key Takeaway: The .gitlab-ci.yml structure is a declarative blueprint where top-level keywords configure the pipeline globally, and named job blocks define the actual work, with GitLab enforcing strict YAML syntax and logical stage-based execution order.