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

The .gitlab-ci.yml File Structure

Explore the anatomy of the CI configuration file, including top-level keywords and pipeline definition basics.

The .gitlab-ci.yml File Structure

You'll learn: How to organize and structure the YAML configuration file that defines your entire GitLab CI/CD pipeline.

What is .gitlab-ci.yml?

The .gitlab-ci.yml file is your pipeline's blueprint—a YAML document stored in your repository's root that tells GitLab exactly what to build, test, and deploy. Think of it as a recipe book where each section describes different cooking steps, ingredients, and when to perform each action.

Core File Anatomy

The .gitlab-ci.yml file uses top-level keywords to define your pipeline structure:

Essential Top-Level Keywords

stages: — Defines the ordered sequence of pipeline phases (e.g., build, test, deploy). Jobs within the same stage run in parallel; stages execute sequentially.

variables: — Sets global environment variables available to all jobs in the pipeline.

default: — Specifies default settings (like before_script or image) inherited by all jobs unless overridden.

Job definitions — Named blocks (e.g., build-job:, test-job:) that define individual work units. Each job specifies:

  • stage: which stage it belongs to
  • script: commands to execute
  • image: Docker image for the runner
  • only/except or rules: when to run

Basic Structure Example

stages:
  - build
  - test

variables:
  DEPLOY_ENV: staging

build-job:
  stage: build
  script:
    - echo "Building application"

test-job:
  stage: test
  script:
    - echo "Running tests"

This structure separates pipeline configuration (stages, global settings) from execution logic (individual jobs), creating a clear hierarchy that GitLab processes sequentially.

Key Takeaway: The .gitlab-ci.yml file uses top-level keywords like stages, variables, and default to configure pipeline-wide settings, while job-specific blocks define the actual work executed by runners—creating a structured, hierarchical pipeline definition.