Course contentsShow
← Cloud and Infrastructure
Lesson 1741 of 2,98936. GitLab CI/CDFree lesson

GitLab CI/CD Pipeline File Structure

Understanding .gitlab-ci.yml structure, syntax, and how GitLab parses pipeline definitions.

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 variables
  • default: - 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 execute
  • stage: - which stage it belongs to (optional, defaults to "test")

Optional job keywords refine behavior:

  • image: - Docker image to use
  • artifacts: - files to preserve
  • cache: - dependencies to speed up runs
  • rules: - 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.