Understanding the hierarchy, precedence, sequencing, and parallelism in GitLab CI/CD pipelines is crucial to mastering how your jobs run, how to optimize them, and how GitLab decides what to execute and when.

Here’s a complete and up-to-date (GitLab 18.0, May 2025) breakdown of the GitLab pipeline execution model:

---

🧱 1. 🔄 GitLab CI/CD Execution Hierarchy

➤ Pipeline (Top-Level Entity)

A single run of your .gitlab-ci.yml file. Triggered by:

• Push/merge/tag
• Schedule
• Manual trigger
• API call

➤ Stages (Sequential Execution Layer)

Defines the order of execution — each stage completes fully before the next begins.

stages:
  - lint
  - test
  - build
  - deploy

➤ Jobs (Inside Each Stage)

All jobs within a stage run in parallel, provided runners are available.

lint:
  stage: lint
  script: npm run lint

unit_test:
  stage: test
  script: npm test

➤ Steps inside a Job

Each job’s script: section contains commands that run sequentially inside the job’s shell or container.

---

🔃 2. Pipeline Execution Flow

Pipeline
 ├── Stage 1: lint
 │    ├── job: lint_a  (parallel)
 │    └── job: lint_b  (parallel)
 ├── Stage 2: test
 │    ├── job: unit_tests
 │    └── job: integration_tests
 ├── Stage 3: build
 │    └── docker_build
 └── Stage 4: deploy
      ├── job: staging_deploy
      └── job: prod_deploy (manual)

---

⏱️ 3. Job Precedence & Order of Execution

✅ Within a Stage:

• Jobs run in parallel
• No strict order unless using needs: (see below)

✅ Between Stages:

• Sequential: Stage 2 starts only if all Stage 1 jobs succeed

---

⚡ 4. How to Run Jobs in Parallel or Control Order

🔹 Parallel Jobs

Jobs in the same stage naturally run in parallel. Example:

test_backend:
  stage: test
  script: run backend tests

test_frontend:
  stage: test
  script: run frontend tests

🔹 Needs: (Run jobs out-of-order / faster)

Allows stage-skipping and job-level dependency. Ideal for reducing pipeline time.

unit_test:
  stage: test
  script: run tests

docker_build:
  stage: build
  script: build docker
  needs: [unit_test]   # Doesn't wait for whole test stage
Code language: PHP (php)

🔹 Dependencies (Job artifact consumption, older method)

Specify jobs that must complete before current job can use their artifacts.

deploy:
  stage: deploy
  dependencies: [build]
Code language: CSS (css)

🔁 Use needs: for parallel dependency-based optimization
📦 Use dependencies: to pass artifacts

---

🧪 5. Conditional Execution (Job-Level Control)

🔸 Rules

Recommended way to control job execution with complex conditions.

job_a:
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
Code language: JavaScript (javascript)

🔸 only/except (Deprecated in favor of rules)

job_b:
  only:
    - branches
    - tags

---

🎯 6. Extended Structures

Structure	Purpose	Notes
Parent-Child Pipelines	Modularize pipelines (include from other .yml)	Ideal for monorepos
Multi-project Pipelines	Trigger another project’s pipeline	Good for microservice chaining
Includes	Reuse YAML templates	From same repo or remote

---

📋 7. Visual: GitLab CI/CD Execution Hierarchy

Pipeline
├── Stages (sequential)
│   ├── Jobs (parallel unless controlled)
│   │   ├── Scripts (sequential commands)
│   │   └── Artifacts/Needs/Dependencies
├── Includes / Child Pipelines (optional)
└── Triggered Pipelines (optional)

---

✅ Summary: Controlling Flow & Parallelism

Control Mechanism	Used For
stages:	Define sequential job groupings
needs:	Define parallel dependencies
rules:	Fine-grained control of job triggers
when:	Delay, manual, or conditional jobs
only/except	Basic conditions (legacy)
dependencies:	Artifact-based job dependencies
trigger:	Trigger child or multi-project pipelines

---