GitLab CI/CD Foundations: .gitlab-ci.yml, Pipelines, Jobs, Stages, and Execution Model: Configuration, Design Choices, and Tradeoffs

1. CI/CD design starts with evidence, not YAML cleverness

A pipeline should answer a delivery question with the least complex trustworthy execution model. “Can this commit build?” “Does this merge request satisfy pre-merge checks?” and “Can this release be deployed?” are different questions. Choosing stages, pipeline source, runner ownership, and identity scope follows from the question and trust boundary.

In Chapter 10, prefer simple, visible causal chains. Chapter 15 introduces DAG optimization; Chapters 12–13 introduce richer creation rules and inputs; Chapter 14 focuses on runners; Chapters 16–21 deepen artifacts, environments, composition, reuse, performance, and cost. Do not import those mechanisms prematurely merely because GitLab supports them.

2. Stages first; DAG later when dependency evidence justifies it

Stages are easy to reason about: jobs within a stage can run in parallel and the next stage waits for the prior stage to succeed. This may serialize independent work, but it gives beginners and operators a clear failure boundary. A DAG using needs can shorten critical paths by expressing job-to-job dependencies directly, but it adds graph complexity and artifact/data-flow considerations.

3. GitLab-hosted versus self-managed runners

A runner decision determines where untrusted repository code executes and what network/filesystem/credentials it can reach. GitLab-hosted runners reduce infrastructure operations; self-managed runners provide environment/network/customization control but make your organization responsible for hardening, patching, isolation, scaling, and credential hygiene.

4. Push/branch pipeline versus merge-request pipeline

A push pipeline commonly has CI_PIPELINE_SOURCE=push and evaluates the pushed ref. A merge-request pipeline uses merge_request_event and exposes MR-specific context. Merely opening an MR does not magically transform every branch pipeline into an MR pipeline; the configuration must opt into MR pipeline behavior through matching rules or equivalent current configuration.

5. Pipeline-source policy belongs at creation time

workflow:rules controls whether a pipeline is created. Job rules decides whether a job is added to an already-created pipeline. Keep those layers separate. A common design bug is enabling both push and MR pipelines unintentionally for the same branch and then interpreting duplicate results as independent evidence.

# Illustration only; Chapter 12 develops rules systematically.
workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_PIPELINE_SOURCE == "push"'

show_source:
  script:
    - printf 'source=%s sha=%s\n' "$CI_PIPELINE_SOURCE" "$CI_COMMIT_SHA"

6. Human-triggered context versus automation identity

The pipeline source and triggering actor influence authorization. A CI_JOB_TOKEN has a restricted resource set and inherits effective capability from the user who triggered the pipeline, subject to job-token policy. That is safer than blindly reusing a long-lived personal token, but it is not a permission bypass.

Design the job so the minimum required capability is obvious. A test job should not need repository push or deployment authority. Later chapters introduce variables/secrets and deployment environments; this chapter’s safest job has no external write access at all.

7. Integrated GitLab CI/CD versus the dedicated CI/CD course

This GitLab course needs substantial CI/CD knowledge because pipelines are woven into merge governance, registries, releases, security, environments, and automation. Chapters 10–21 therefore teach the execution and platform integration model needed to operate GitLab safely.

The separate GitLab CI/CD course can go deeper into specialized syntax patterns, ecosystem integrations, advanced reusable architectures, runner fleets, performance tuning, and pipeline engineering without forcing every GitLab platform learner through all niche details. The boundary is deliberate: learn enough here to reason about GitLab as a delivery platform, then deepen CI/CD specialization separately.

8. Worked decision: a small service team

Scenario: six developers maintain an ordinary web service. They need fast pre-merge confidence, have no private-network test dependency, and do not want to administer runner infrastructure yet.

9. Design anti-patterns to reject

• “Put every job in one stage for speed.” This erases useful gates and dependency meaning.
• “Use our production shell runner because it is already online.” Availability is not a trust justification.
• “Give CI a broad PAT so every integration works.” Long-lived ambient authority expands blast radius.
• “A branch pipeline is enough for all MR decisions.” It may lack the MR source/context your policy expects.
• “Optimize DAG/cache before measuring.” Complexity without bottleneck evidence reduces maintainability.

Knowledge check

Summary

CI/CD architecture is a set of policy choices: graph complexity, pipeline source, runner ownership, and job identity. Start with a simple pipeline whose evidence is easy to explain; add DAGs, specialized runners, or broader integration only when requirements justify their trust, operational, and cost consequences.

Official references

• GitLab Docs — CI/CD
• GitLab Docs — Get started with GitLab CI/CD
• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — Validate CI/CD configuration
• GitLab Docs — Pipeline editor
• GitLab Docs — Pipelines
• GitLab Docs — CI/CD jobs
• GitLab Docs — Job execution flow
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — CI/CD variables
• GitLab Docs — CI/CD job token
• GitLab Docs — Runners
• GitLab Docs — Configure runners
• GitLab Docs — GitLab-hosted runners
• GitLab Docs — Pipelines API
• GitLab Docs — Jobs API
• GitLab Docs — CI Lint API
• GitLab Docs — Job rules and CI_PIPELINE_SOURCE
• GitLab CLI — ci
• GitLab CLI — ci list
• GitLab CLI — ci get
• GitLab CLI — ci status
• GitLab CLI — runner list