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 toscript:commands to executeimage:Docker image for the runneronly/exceptorrules: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.