GitLab CI/CD Tutorial: Pipelines, Jobs & Real-World Workflows

# Define the order of stages — jobs in the same stage run in parallel
# Jobs in later stages only run if all jobs in prior stages pass
stages:
  - install      # Stage 1: Get dependencies ready
  - test         # Stage 2: Run all automated tests
  - build        # Stage 3: Compile/bundle the application
  - deploy       # Stage 4: Ship to the target environment

# A default block applies settings to ALL jobs unless a job overrides them
default:
  image: node:20-alpine  # Every job runs inside this Docker container
  before_script:
    - echo "Pipeline started for branch: $CI_COMMIT_BRANCH"

# ── STAGE: install ──────────────────────────────────────────────────────────
install_dependencies:
  stage: install
  script:
    - npm ci  # 'ci' is stricter than 'install' — uses package-lock.json exactly
  # Cache node_modules so later stages (and future pipelines) don't re-download
  cache:
    key:
      files:
        - package-lock.json   # Cache is invalidated only when lock file changes
    paths:
      - node_modules/
  artifacts:
    paths:
      - node_modules/         # Pass node_modules to downstream jobs in this pipeline
    expire_in: 1 hour         # Don't keep artifacts forever — saves storage

# ── STAGE: test ─────────────────────────────────────────────────────────────
run_unit_tests:
  stage: test
  script:
    - npm run test:unit -- --coverage  # Run unit tests and generate coverage report
  coverage: '/Lines\s*:\s*(\d+\.?\d*)%/'  # Regex to parse coverage % from output
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml  # Shown as coverage badge in GitLab UI

run_lint:
  stage: test   # Runs in PARALLEL with run_unit_tests — same stage
  script:
    - npm run lint  # Code style check — runs at the same time as unit tests

# ── STAGE: build ─────────────────────────────────────────────────────────────
build_production_bundle:
  stage: build
  script:
    - npm run build  # Creates optimised production assets in /dist
  artifacts:
    paths:
      - dist/         # Pass the compiled app to the deploy stage
    expire_in: 1 week

# ── STAGE: deploy ─────────────────────────────────────────────────────────────
deploy_to_production:
  stage: deploy
  script:
    - echo "Deploying commit $CI_COMMIT_SHA to production..."
    - ./scripts/deploy.sh  # Your actual deployment script
  environment:
    name: production
    url: https://myapp.example.com
  # CRITICAL: Only deploy automatically from the main branch
  # All other branches can run tests and build, but NOT deploy
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: on_success   # Deploy automatically if all prior stages passed
    - when: never        # For any other branch, skip this job entirely

# ── DEMONSTRATING THE DIFFERENCE BETWEEN CACHE AND ARTIFACTS ────────────────

stages:
  - dependencies
  - test
  - package

install_python_packages:
  stage: dependencies
  image: python:3.12-slim
  script:
    - pip install -r requirements.txt --target=.packages
  cache:
    # Cache key is a hash of requirements.txt
    # The cache is ONLY invalidated when requirements.txt changes
    # This saves ~30-60s on pipelines where nothing changed
    key:
      files:
        - requirements.txt
    paths:
      - .packages/     # Cached across pipelines for speed
  artifacts:
    paths:
      - .packages/     # Also an artifact so test stage can USE these packages
    expire_in: 2 hours

run_pytest:
  stage: test
  image: python:3.12-slim
  script:
    # PYTHONPATH tells Python where to find the packages installed above
    - export PYTHONPATH="$CI_PROJECT_DIR/.packages:$PYTHONPATH"
    - python -m pytest tests/ -v --junitxml=report.xml
  artifacts:
    # Test reports are artifacts — GitLab reads them to display pass/fail in MR UI
    reports:
      junit: report.xml   # Displays individual test results in the merge request
    when: always          # Upload report EVEN if tests fail — you need the evidence

create_deployment_package:
  stage: package
  image: python:3.12-slim
  script:
    - zip -r deployment.zip src/ .packages/ config/
    - echo "Package size: $(du -sh deployment.zip | cut -f1)"
  artifacts:
    name: "app-package-$CI_COMMIT_SHORT_SHA"  # Dynamic name includes commit hash
    paths:
      - deployment.zip
    expire_in: 1 week   # Keep for a week so you can re-deploy without re-building
    # Note: NO cache here — the zip file is a one-off per pipeline, not reusable

# ── MULTI-ENVIRONMENT DEPLOYMENT PIPELINE ────────────────────────────────────
# This demonstrates: review apps, staging, and production with proper guards

stages:
  - test
  - deploy

variables:
  # These non-sensitive defaults can live in the YAML
  STAGING_URL: "https://staging.myapp.example.com"
  PRODUCTION_URL: "https://myapp.example.com"
  # DEPLOY_SSH_KEY and PRODUCTION_API_KEY are set in
  # GitLab Settings > CI/CD > Variables (masked + protected)

# ── Shared test job (runs for ALL branches) ───────────────────────────────────
run_all_tests:
  stage: test
  image: node:20-alpine
  script:
    - npm ci
    - npm test

# ── REVIEW APP: Deploys for every Merge Request ───────────────────────────────
deploy_review_app:
  stage: deploy
  image: alpine:latest
  script:
    # CI_ENVIRONMENT_SLUG is auto-generated from the environment name
    # e.g., environment name "review/fix-login-bug" becomes slug "review-fix-login-bug"
    - echo "Deploying review app for MR: $CI_MERGE_REQUEST_IID"
    - apk add --no-cache openssh-client rsync
    - ./scripts/deploy-review.sh $CI_ENVIRONMENT_SLUG  # Your deploy script
  environment:
    name: review/$CI_COMMIT_REF_SLUG   # Creates a unique environment per branch
    url: https://$CI_ENVIRONMENT_SLUG.review.myapp.example.com
    on_stop: teardown_review_app       # Tell GitLab which job cleans this up
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'  # Only runs for MRs

# ── Teardown job: Runs when MR is closed or merged ───────────────────────────
teardown_review_app:
  stage: deploy
  image: alpine:latest
  script:
    - echo "Tearing down review app: $CI_ENVIRONMENT_SLUG"
    - ./scripts/teardown-review.sh $CI_ENVIRONMENT_SLUG
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop   # This is what links it to the on_stop in deploy_review_app
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: manual  # Triggered manually OR automatically when MR closes

# ── STAGING: Deploys automatically when develop branch is updated ─────────────
deploy_to_staging:
  stage: deploy
  image: alpine:latest
  script:
    - echo "Deploying $CI_COMMIT_SHORT_SHA to staging..."
    - ./scripts/deploy.sh staging
  environment:
    name: staging
    url: $STAGING_URL
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'
      when: on_success

# ── PRODUCTION: Requires manual approval — never deploys automatically ─────────
deploy_to_production:
  stage: deploy
  image: alpine:latest
  script:
    - echo "Deploying $CI_COMMIT_SHORT_SHA to PRODUCTION"
    - ./scripts/deploy.sh production
  environment:
    name: production
    url: $PRODUCTION_URL
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual        # A human must click 'Run' in the GitLab UI to proceed
      allow_failure: false  # If this job fails, the pipeline is marked failed

# ── OPTIMISED PIPELINE USING DAG + PARALLEL MATRIX + CHANGE DETECTION ────────

stages:
  - install
  - test          # In default mode, everything here waits for install to finish
  - build         # In default mode, everything here waits for ALL tests to pass
  - deploy

install_node_modules:
  stage: install
  image: node:20-alpine
  script:
    - npm ci
  cache:
    key:
      files: [package-lock.json]
    paths: [node_modules/]
  artifacts:
    paths: [node_modules/]
    expire_in: 1 hour

# ── PARALLEL MATRIX: Runs 3 simultaneous jobs instead of 3 sequential ones ───
test_across_node_versions:
  stage: test
  # 'needs' tells GitLab: start me as soon as install_node_modules passes
  # Don't wait for other jobs in the install stage that don't affect me
  needs: ["install_node_modules"]
  parallel:
    matrix:
      # GitLab spins up 3 separate jobs, one per entry — all run at the same time
      - NODE_VERSION: "18"
      - NODE_VERSION: "20"
      - NODE_VERSION: "22"
  image: node:${NODE_VERSION}-alpine  # Each job uses its own Node version
  script:
    - echo "Testing on Node $NODE_VERSION"
    - npm test
    - echo "Node $NODE_VERSION — PASSED"

# ── CHANGE-BASED SKIPPING: Only rebuild if source code actually changed ───────
build_docker_image:
  stage: build
  image: docker:24
  services:
    - docker:24-dind  # Docker-in-Docker: lets you build Docker images inside CI
  needs:
    # DAG: start building as soon as tests pass — don't wait for other build jobs
    - job: test_across_node_versions
  script:
    - docker build -t myapp:$CI_COMMIT_SHORT_SHA .
    - docker push myregistry.example.com/myapp:$CI_COMMIT_SHORT_SHA
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      changes:
        # Only run this job if one of these paths changed
        # A docs-only push? This job is SKIPPED entirely
        - src/**/*
        - Dockerfile
        - package.json
        - package-lock.json

# ── VISUALISING THE DAG EFFECT ────────────────────────────────────────────────
# WITHOUT needs (default stage ordering):
#   install(42s) → test_node18(3m) → test_node20(3m) → test_node22(3m) → build(2m)
#   Total: ~11 minutes sequential
#
# WITH needs + parallel matrix:
#   install(42s) → [test_node18 + test_node20 + test_node22](3m parallel) → build(2m)
#   Total: ~6 minutes  ← Almost 2x faster with zero new hardware