🚀 GitLab CI/CD — Roadmap & Deep Dive Guide

Author: Special thanks to anIcedAntFA
Từ zero đến production-grade pipeline cho React SPA.

Target audience: Frontend developer muốn hiểu CI/CD từ gốc, áp dụng cho real-world project

📑 Table of Contents

• Part 1: Roadmap — Từ cơ bản đến nâng cao
  • Level 1: Core Concepts
  • Level 2: YAML Syntax Mastery
  • Level 3: Pipeline Architecture
  • Level 4: Advanced Patterns
  • Level 5: Production-Grade
• Part 2: Real world Pipeline — Deep Dive
  • Phân tích pipeline hiện tại
  • Vấn đề và cải thiện
• Part 3: Code Quality Stage — Thiết kế & Triển khai
  • Tại sao cần CI-level checks?
  • Recommended structure
  • Cấu hình chi tiết
  • Pipeline hoàn chỉnh (proposed)
• Part 4: AWS Integration — S3, CloudFront, ECR
• Part 5: Best Practices & Common Pitfalls
• Part 6: Giải thích chi tiết — Các khái niệm dễ nhầm lẫn
  • 16. GitLab CI Cache — Deep Dive (Real Pipeline Observations)
  • 17. Deploy Scripts — Giải thích từng dòng
  • 18. Pipeline Behavior trên MR — Quan sát thực tế
  • 19. Cache Best Practices — Tối ưu cho Real World Pipeline
  • 20. Deploy Image Optimization — Bake tools vào Docker image
  • 21. Rules Syntax Deep Dive — Best practices cho rules:if
  • 22. Quality Stage Scope — Nên chạy quality ở đâu?
  • 23. Docker Image Anatomy — Giải thích từng dòng Dockerfile
  • 24. Tại sao GitLab gộp CI và CD vào 1 file .gitlab-ci.yml?
  • 25. Cache key:files — OR hay AND? package.json vs bun.lock
  • 26. Tại sao tách stages thay vì gộp tất cả vào 1 stage?
  • 27. Notify Stage — needs:optional, artifacts: false, rules:variables, allow_failure

Part 1: Roadmap — Từ cơ bản đến nâng cao

Level 1: Core Concepts

🎯 Hiểu CI/CD là gì, tại sao cần, pipeline hoạt động ra sao.

CI/CD là gì?

CI (Continuous Integration)     → Tự động build + test mỗi khi push code
CD (Continuous Delivery)        → Tự động deploy đến staging/production
CD (Continuous Deployment)      → Deploy tự động hoàn toàn, không cần manual approval

Mental Model

graph LR
    A["👨‍💻 Developer<br/>git push"] --> B["🔀 GitLab<br/>detects .gitlab-ci.yml"]
    B --> C["⚙️ Runner<br/>picks up job"]
    C --> D["📦 Docker<br/>spins up container"]
    D --> E["🏗️ Build<br/>bun install + build"]
    E --> F["✅ Pass / ❌ Fail"]
    F --> G["📬 Notification"]

Bộ ba cốt lõi

File .gitlab-ci.yml

Đặt ở root project. GitLab đọc file này mỗi khi có event (push, MR, tag, schedule).

# Simplest possible pipeline
stages:
  - build
  - test
  - deploy

build_job:
  stage: build
  script:
    - echo "Building..."

test_job:
  stage: test
  script:
    - echo "Testing..."

deploy_job:
  stage: deploy
  script:
    - echo "Deploying..."

Execution Flow

push code → GitLab reads .gitlab-ci.yml
                ↓
         Creates pipeline
                ↓
    ┌─── Stage: build ───┐
    │  build_job (running) │
    └─────────────────────┘
                ↓ (all pass)
    ┌─── Stage: test ────┐
    │  test_job (running)  │
    └─────────────────────┘
                ↓ (all pass)
    ┌─── Stage: deploy ──┐
    │ deploy_job (running) │
    └─────────────────────┘
                ↓
         Pipeline: ✅ passed

Rules:

• Jobs trong cùng stage → chạy song song
• Stage tiếp theo → chỉ bắt đầu khi stage trước hoàn thành thành công
• 1 job fail → pipeline fail → stages sau không chạy

GitLab Runner

Runner là agent thực thi jobs. Có 3 loại:

Real World dùng: runner-linux — shared runner tự động scale.

Docker Image trong CI

Mỗi job chạy trong 1 Docker container riêng:

job:
  image: node:22.14.0-slim # Container environment
  script:
    - node --version # Chạy trong container này

Real World dùng image custom đã cài sẵn bun:

registry-gitlab.com/feel-free/node:22.14.0-slim

Level 2: YAML Syntax Mastery

🎯 Nắm vững tất cả keywords quan trọng.

Global Keywords

# ① stages — Định nghĩa thứ tự stages
stages:
  - build
  - test
  - deploy

# ② variables — Biến dùng chung cho tất cả jobs
variables:
  APP_NAME: feel-free
  NODE_ENV: production

# ③ default — Giá trị mặc định cho tất cả jobs
default:
  image: node:22-slim
  tags:
    - runner-linux
  retry: 1

# ④ workflow — Điều kiện để pipeline được tạo
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "develop"
    - if: $CI_COMMIT_BRANCH == "master"

# ⑤ include — Import config từ file/project khác
include:
  - local: '/.gitlab/ci/quality.yml'
  - template: Jobs/SAST.gitlab-ci.yml

Job Keywords — Cheat Sheet

job_name: # Tên job (unique)
  stage: build # Thuộc stage nào
  image: node:22-slim # Docker image
  tags: # Runner tags
    - linux
  variables: # Job-scoped variables
    MODE: development
  before_script: # Chạy trước script
    - echo "Starting..."
  script: # ⚠️ BẮT BUỘC — Commands chính
    - bun install
    - bun run build
  after_script: # Luôn chạy (kể cả fail)
    - echo "Done."
  artifacts: # Files truyền qua stages
    paths: ['dist/']
    expire_in: '3 mos'
    when: on_success
  cache: # Files cache giữa các runs
    key:
      files: [bun.lock]
    paths: [node_modules]
    policy: pull-push
  dependencies: # Chỉ lấy artifacts từ jobs cụ thể
    - build_job
  rules: # Điều kiện chạy job (thay only/except)
    - if: $CI_COMMIT_BRANCH == "develop"
      when: always
    - if: $CI_MERGE_REQUEST_ID
      when: always
  needs: # Chạy sớm, không đợi stage order
    - build_job
  when: on_success # Khi nào chạy: on_success|on_failure|always|manual|delayed
  allow_failure: false # Cho phép fail mà pipeline vẫn pass?
  interruptible: true # Có thể cancel khi có commit mới?
  timeout: 10 minutes # Giới hạn thời gian chạy
  retry: 2 # Số lần retry nếu fail
  environment: # Đánh dấu deploy environment
    name: production
    url: https://www.feel-free.com

only/except vs rules (Modern)

# ❌ Legacy — only/except (deprecated dần)
job:
  only:
    - develop
  except:
    - tags

# ✅ Modern — rules (linh hoạt hơn, rõ ràng hơn)
job:
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - when: never  # default: không chạy

rules Deep Dive

rules:
  # ① if — Điều kiện biến
  - if: $CI_COMMIT_BRANCH == "develop"
    when: always

  # ② changes — File thay đổi
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    changes:
      - src/**/*.{ts,tsx}
      - package.json
    when: on_success

  # ③ exists — File tồn tại
  - exists:
      - Dockerfile
    when: manual

  # ④ Kết hợp if + changes
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    changes:
      - '**/*.scss'
    variables:
      RUN_STYLE_CHECK: 'true'

Artifacts vs Cache

# Artifacts — truyền dist/ từ build → deploy
build:
  script: bun run build
  artifacts:
    paths: ["dist/"]
    expire_in: "3 mos"

# Cache — giữ node_modules giữa các runs
build:
  cache:
    key:
      files: [bun.lock]
    paths: [node_modules]

Variables

# ① Global variables (tất cả jobs)
variables:
  APP_NAME: feel-free

# ② Job variables (chỉ job đó)
job:
  variables:
    MODE: development

# ③ Predefined variables (GitLab tự tạo)
script:
  - echo $CI_COMMIT_BRANCH # develop
  - echo $CI_MERGE_REQUEST_ID # 42
  - echo $CI_PIPELINE_SOURCE # merge_request_event
  - echo $CI_PROJECT_DIR # /builds/corp/feel-free
  - echo $CI_COMMIT_SHORT_SHA # a1b2c3d4


# ④ Protected variables (Settings > CI/CD > Variables)
# AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
# Chỉ available ở protected branches (master, develop)

Hidden Jobs & Templates

# Dấu chấm (.) = hidden job, không chạy, dùng làm template
.node_template:
  image: node:22-slim
  tags:
    - runner-linux
  cache:
    key:
      files: [bun.lock]
    paths: [node_modules]
    policy: pull

# extends — kế thừa template
lint_job:
  extends: .node_template
  stage: quality
  script:
    - bun run lint

YAML Anchors

# & = define anchor, * = reference anchor
.default_cache: &default_cache
  key:
    files: [bun.lock]
  paths: [node_modules]
  policy: pull

job1:
  cache:
    <<: *default_cache
    policy: pull-push # Override

job2:
  cache: *default_cache # Dùng nguyên

Level 3: Pipeline Architecture

🎯 Thiết kế pipeline hiệu quả, chọn pattern phù hợp.

Pattern 1: Basic Pipeline

# Sequential stages — simple, dễ hiểu
stages:
  - quality
  - build
  - deploy
# Tất cả quality jobs chạy song song
# → Xong hết → build jobs chạy
# → Xong hết → deploy jobs chạy

┌─── quality ──────────────┐
│ lint │ format │ typecheck │  ← song song
└──────────────────────────┘
              ↓
┌─── build ────────────────┐
│        build_app          │
└──────────────────────────┘
              ↓
┌─── deploy ───────────────┐
│       deploy_app          │
└──────────────────────────┘

Pattern 2: DAG Pipeline (needs)

# Directed Acyclic Graph — jobs chạy ngay khi dependency xong
lint:
  stage: quality
  needs: [] # Chạy ngay, không đợi gì
  script: bun run lint

build:
  stage: build
  needs: [] # Cũng chạy ngay (song song với lint)
  script: bun run build

deploy:
  stage: deploy
  needs: [build] # Chỉ đợi build xong
  script: deploy.sh

lint ─────────────→ (không cần đợi)
build ────────────→ deploy
                      ↑
                 chỉ đợi build

Pattern 3: Parent-Child Pipeline

# Parent triggers child pipelines
# Tốt cho monorepo hoặc pipeline phức tạp

# .gitlab-ci.yml (parent)
stages:
  - triggers

frontend:
  trigger:
    include: frontend/.gitlab-ci.yml
  rules:
    - changes: ['frontend/**/*']

backend:
  trigger:
    include: backend/.gitlab-ci.yml
  rules:
    - changes: ['backend/**/*']

Chọn pattern nào cho Real World?

Recommendation: Basic Pipeline + thêm quality stage là đủ cho Real World.

Level 4: Advanced Patterns

🎯 Tối ưu performance, DRY configuration, conditional logic.

include — Tách file config

# .gitlab-ci.yml
include:
  - local: '.gitlab/ci/quality.yml' # Quality jobs
  - local: '.gitlab/ci/build.yml' # Build jobs
  - local: '.gitlab/ci/deploy.yml' # Deploy jobs

stages:
  - quality
  - build_app
  - deploy_app

variables:
  APP_NAME: feel-free

extends — DRY Templates

# Template cho tất cả Node.js jobs
.node_base:
  image: registry-gitlab.com/feel-free/node:22.14.0-slim
  tags:
    - runner-linux
  cache:
    key:
      files: [bun.lock]
    paths: [node_modules]
    policy: pull

# Template cho deploy jobs
.deploy_base:
  image: docker.com/alpine:latest
  tags:
    - runner-linux
  before_script:
    - apk add --update bash py-pip
    - pip install awscli --upgrade --user --break-system-packages
    - export PATH=/root/.local/bin:$PATH

# Kế thừa
lint:
  extends: .node_base
  script: bun run lint

deploy_dev:
  extends: .deploy_base
  script: aws s3 cp ./dist s3://my-${APP_NAME} --recursive

parallel:matrix — Matrix Builds

# Chạy cùng job với nhiều biến khác nhau
quality:
  stage: quality
  parallel:
    matrix:
      - CHECK: [lint, format:check, style, type-check, circular]
  script:
    - bun run $CHECK

Environment & Review Apps

deploy_review:
  stage: deploy
  script: deploy-to-review.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.feel-free.com
    auto_stop_in: 1 week
  rules:
    - if: $CI_MERGE_REQUEST_ID

resource_group — Prevent Concurrent Deploys

deploy_production:
  stage: deploy
  resource_group: production # Chỉ 1 deploy chạy cùng lúc
  script: deploy.sh

Level 5: Production-Grade

🎯 Security, monitoring, optimization.

Protected Variables

Settings > CI/CD > Variables:
  AWS_ACCESS_KEY_ID      → Protected + Masked
  AWS_SECRET_ACCESS_KEY  → Protected + Masked
  SENTRY_DSN             → Protected

Protected = chỉ available ở protected branches (master, develop). Masked = không hiển thị trong job logs.

Pipeline Security Best Practices

# ① Limit pipeline creation
workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH =~ /^(master|develop|qa)$/
    - when: never

# ② Auto-cancel redundant pipelines
workflow:
  auto_cancel:
    on_new_commit: interruptible

# ③ Timeout để tránh runner bị stuck
default:
  timeout: 15 minutes

# ④ Interruptible jobs
quality_job:
  interruptible: true  # Cancel được khi có commit mới

Monitoring & Notifications

# Slack/webhook notification on failure
notify_failure:
  stage: .post
  script:
    - curl -X POST $SLACK_WEBHOOK -d '{"text":"Pipeline failed: '$CI_PIPELINE_URL'"}'
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
      when: on_failure

Scheduled Pipelines

Settings > CI/CD > Schedules:
  - "Nightly build check" → cron: 0 3 * * * → branch: develop
  - "Weekly dependency audit" → cron: 0 9 * * 1 → branch: develop

Part 2: Real World Pipeline — Deep Dive

Phân tích pipeline hiện tại

Overview

stages:
  - build_app
  - deploy_app

Pipeline hiện tại có 2 stages, 7 jobs chạy theo branch:

graph TB
    subgraph "Trigger: merge_request"
        MR["merge_build_app<br/>bun install + build"]
    end

    subgraph "Trigger: develop branch"
        DB["dev_build_app<br/>bun install + build --mode development"]
        DB --> DD["dev_deploy_app<br/>S3 + CloudFront invalidation"]
    end

    subgraph "Trigger: qa branch"
        TB_["test_build_app<br/>bun install + build --mode test"]
        TB_ --> TD["test_deploy_app<br/>S3 + CloudFront invalidation"]
    end

    subgraph "Trigger: master branch"
        LB["live_build_app<br/>bun install + build"]
        LB --> LD["live_deploy_app<br/>S3 + CloudFront invalidation"]
    end

    style MR fill:#aqweqw,color:#fff
    style DB fill:#sas2f0,color:#fff
    style DD fill:#339af0,color:#fff
    style TB_ fill:#sasd2as,color:#fff
    style TD fill:#sasd2as,color:#fff
    style LB fill:#22sasdz,color:#fff
    style LD fill:#22sasdz,color:#fff

Job-by-Job Analysis

1. merge_build_app — MR Validation

merge_build_app:
  image: registry-feel-free.com/.../node:22.14.0-slim
  only:
    - merge_request
  script:
    - bun install
    # - yarn test --silent    ← ⚠️ Tests commented out!
    - bun run build
  stage: build_app
  tags:
    - runner-linux
  when: always

⚠️ Issues:

1. Không cache node_modules → chậm (install lại mỗi lần)
2. Tests bị comment out → không validate logic
3. Không check lint/format → code quality hoàn toàn phụ thuộc pre-commit

2. dev_build_app — Development Build

dev_build_app:
  cache:
    key:
      files:
        - bun.lock
        - bun.lockb
    paths:
      - node_modules
    policy: pull-push
    untracked: true # ⚠️ Cache cả untracked files
  script:
    - bun install
    - bun run build --mode development
  artifacts:
    paths: ['dist/']
    when: on_success
    expire_in: '3 mos'
  only:
    - develop

⚠️ Issues:

1. untracked: true → cache tất cả untracked files, có thể include dist/, temp files → bloat cache
2. bun.lockb trong cache key → bun >= 1.2 chỉ dùng bun.lock (text-based), bun.lockb legacy

3. dev_deploy_app — Deploy to Dev S3

dev_deploy_app:
  image: docker.com/alpine:latest
  before_script:
    - apk add --update bash
    - apk add --update py-pip
    - pip install awscli --upgrade --user --break-system-packages
  script:
    - export AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
    - export AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
    - export PATH=/root/.local/bin:$PATH
    - aws s3 rm s3://my-${APP_NAME} --recursive --only-show-errors
    - aws s3 cp ./dist s3://my-${APP_NAME} --recursive --only-show-errors --cache-control max-age=180
    - aws cloudfront create-invalidation --distribution-id ${DEV_CLOUDFRONT_ID} --paths "/*"
  dependencies:
    - dev_build_app
  only:
    - develop

Deploy flow:

dist/ (artifact) → S3 bucket (my-feel-free)
                         ↓
                   CloudFront (XXX-XXX-XXX)
                         ↓
                   Cache invalidation "/*"
                         ↓
                   dev.feel-free.com ✅

⚠️ Issues:

1. Cài awscli từ đầu mỗi lần deploy → chậm (~30-60s). Nên dùng image có sẵn AWS CLI.
2. aws s3 rm --recursive rồi aws s3 cp → có downtime ngắn giữa xóa và upload. Nên dùng aws s3 sync --delete thay thế.
3. export AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} → thừa, GitLab CI/CD variables đã tự export.
4. --cache-control max-age=180 → tất cả files cùng cache policy. Thực tế:
   • index.html → no-cache (luôn check mới nhất)
   • assets/* (có content hash) → max-age=31536000 (1 năm)

4-7. Test & Live — Pattern lặp lại

test_build_app → test_deploy_app  (qa branch → stg-feel-free S3)
live_build_app → live_deploy_app  (master branch → live-feel-free S3)

Cùng pattern, chỉ khác --mode và S3 bucket/CloudFront ID.

Tổng hợp vấn đề

Vấn đề và cải thiện

Cải thiện ngay (Quick Wins)

1. Thêm cache cho MR job

merge_build_app:
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull # ← Chỉ đọc cache, không ghi (MR không pollute cache)

2. Dùng aws s3 sync thay vì rm + cp

# Before (downtime)
- aws s3 rm s3://my-${APP_NAME} --recursive
- aws s3 cp ./dist s3://my-${APP_NAME} --recursive

# After (atomic, no downtime)
- aws s3 sync ./dist s3://my-${APP_NAME} --delete --only-show-errors --cache-control max-age=180

3. Loại bỏ export thừa

# Before
- export AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
- export AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
# After — không cần, GitLab CI/CD variables đã là env vars
# (xóa 2 dòng này)

Part 3: Code Quality Stage — Thiết kế & Triển khai

Tại sao cần CI-level checks?

Vấn đề: --no-verify Bypass

# Developer commit bình thường → Husky chạy lint-staged
git commit -m "feat: add button"
# ✅ eslint --fix → prettier --write → stylelint --fix

# Developer bypass pre-commit
git commit -m "feat: add button" --no-verify
# ❌ KHÔNG check gì cả → code lỗi merge vào develop

Tình huống thực tế:

1. Developer đang fix gấp bug production
2. Pre-commit fail vì unrelated lint error
3. --no-verify để commit nhanh
4. Merge request được approve (reviewer không check lint)
5. Develop branch có code không đạt chuẩn

Defense in Depth

Layer 1: IDE         → ESLint/Prettier extensions (real-time)     ← Optional
Layer 2: Pre-commit  → Husky + lint-staged (local)                ← Bypassable
Layer 3: CI Pipeline → Quality stage (server-side)                ← 🛡️ UNBYPASSABLE
Layer 4: MR Rules    → Pipeline must pass before merge            ← Enforced by GitLab

📌 CI là layer duy nhất không thể bypass. Nếu pipeline fail → MR không merge được.

Config GitLab: Enforce Pipeline Pass

Settings > Merge requests > Merge checks:
  ☑️ Pipelines must succeed
  ☑️ All threads must be resolved

Recommended Structure

Các checks cần chạy

bun run lint          → ESLint (code quality, best practices)
bun run format:check  → Prettier (formatting consistency)
bun run style         → Stylelint (CSS/SCSS quality)
bun run type-check    → TypeScript (type safety)
bun run circular      → dpdm (circular dependency detection)
bun run test          → Vitest (unit tests)

Nên check hết hay chọn lọc?

Verdict: Check tất cả, nhưng chạy song song.

Lý do:

1. Mỗi check phát hiện loại vấn đề khác nhau — không thể thay thế lẫn nhau
2. Chạy song song → tổng thời gian = check chạy lâu nhất (không phải tổng cộng)
3. Chi phí bỏ lỡ > chi phí chạy thêm vài phút CI

Chiến lược: Parallel Jobs

┌─── quality (song song) ──────────────────────────────────┐
│ lint │ format │ stylelint │ type-check │ circular │ test │
└──────────────────────────────────────────────────────────┘
                           ↓ (all pass)
┌─── build_app ────────────────────────────────────────────┐
│                      build                                │
└──────────────────────────────────────────────────────────┘
                           ↓ (pass)
┌─── deploy_app ───────────────────────────────────────────┐
│                      deploy                               │
└──────────────────────────────────────────────────────────┘

Tổng thời gian quality stage ≈ max(lint, format, stylelint, type-check, circular, test) vì chạy song song.

Cấu hình chi tiết

Template chung

# Hidden job — base template cho tất cả quality jobs
.quality_base:
  image: registry-gitlab.com/feel-free/node:22.14.0-slim
  stage: quality
  tags:
    - runner-linux
  interruptible: true # Cancel khi có commit mới
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull # Chỉ đọc cache
  before_script:
    - bun install --frozen-lockfile
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH =~ /^(develop|qa|master)$/

Từng quality job

# ① ESLint — Code quality
quality:lint:
  extends: .quality_base
  script:
    - bun run lint

# ② Prettier — Formatting
quality:format:
  extends: .quality_base
  script:
    - bun run format:check

# ③ Stylelint — CSS/SCSS quality
quality:style:
  extends: .quality_base
  script:
    - bun run style

# ④ TypeScript — Type safety
quality:type-check:
  extends: .quality_base
  script:
    - bun run type-check

# ⑤ Circular dependencies
quality:circular:
  extends: .quality_base
  script:
    - bun run circular

# ⑥ Unit tests
quality:test:
  extends: .quality_base
  script:
    - bun run test --run --reporter=default --reporter=junit --outputFile=stg-report.xml
  artifacts:
    when: always
    reports:
      junit: stg-report.xml # GitLab hiển thị test results trong MR
  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/' # Parse coverage từ output

Tại sao dùng --frozen-lockfile?

bun install --frozen-lockfile
# → Không modify bun.lock
# → Fail nếu bun.lock không match package.json
# → Đảm bảo CI install ĐÚNG versions đã commit

Tại sao interruptible: true?

Developer push commit 1 → Pipeline A starts (quality checks running)
Developer push commit 2 → Pipeline B starts
                         → Pipeline A: quality jobs CANCELLED (tiết kiệm runner)
                         → Pipeline B: quality jobs running (latest code)

Pipeline hoàn chỉnh (proposed)

Stage flow mới

stages:
  - quality # ← NEW: lint, format, style, type-check, circular, test
  - build_app
  - deploy_app

Proposed .gitlab-ci.yml

stages:
  - quality
  - build_app
  - deploy_app

variables:
  APP_NAME: feel-free
  DEV_CLOUDFRONT_ID: XXX-XXX-XXX
  TEST_CLOUDFRONT_ID: XXX-XXX-XXX
  LIVE_CLOUDFRONT_ID: XXX-XXX-XXX

workflow:
  auto_cancel:
    on_new_commit: interruptible

# ========================================
# Templates
# ========================================

.node_base:
  image: registry-gitlab.com/feel-free/node:22.14.0-slim
  tags:
    - runner-linux
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull

.quality_base:
  extends: .node_base
  stage: quality
  interruptible: true
  before_script:
    - bun install --frozen-lockfile
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH =~ /^(develop|qa|master)$/

.deploy_base:
  stage: deploy_app
  image: docker.com/alpine:latest
  tags:
    - runner-linux
  before_script:
    - apk add --update bash py-pip
    - pip install awscli --upgrade --user --break-system-packages
    - export PATH=/root/.local/bin:$PATH
  when: on_success

# ========================================
# Quality Stage (parallel)
# ========================================

quality:lint:
  extends: .quality_base
  script:
    - bun run lint

quality:format:
  extends: .quality_base
  script:
    - bun run format:check

quality:style:
  extends: .quality_base
  script:
    - bun run style

quality:type-check:
  extends: .quality_base
  script:
    - bun run type-check

quality:circular:
  extends: .quality_base
  script:
    - bun run circular

quality:test:
  extends: .quality_base
  script:
    - bun run test --run --reporter=default --reporter=junit --outputFile=stg-report.xml
  artifacts:
    when: always
    reports:
      junit: stg-report.xml
  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'

# ========================================
# Merge Request Build
# ========================================

merge_build_app:
  extends: .node_base
  stage: build_app
  script:
    - bun install --frozen-lockfile
    - bun run build
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

# ========================================
# DEV (develop branch)
# ========================================

dev_build_app:
  extends: .node_base
  stage: build_app
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull-push # Ghi cache cho dev
  script:
    - bun install
    - bun run build --mode development
  artifacts:
    paths: ['dist/']
    when: on_success
    expire_in: '3 mos'
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

dev_deploy_app:
  extends: .deploy_base
  script:
    - aws s3 sync ./dist s3://my-${APP_NAME} --delete --only-show-errors --cache-control max-age=180
    - aws cloudfront create-invalidation --distribution-id ${DEV_CLOUDFRONT_ID} --paths "/*"
  dependencies:
    - dev_build_app
  rules:
    - if: $CI_COMMIT_BRANCH == "develop"

# ========================================
# TEST (qa branch)
# ========================================

test_build_app:
  extends: .node_base
  stage: build_app
  script:
    - bun install --frozen-lockfile
    - bun run build --mode test
  artifacts:
    paths: ['dist/']
    when: on_success
    expire_in: '3 mos'
  rules:
    - if: $CI_COMMIT_BRANCH == "qa"

test_deploy_app:
  extends: .deploy_base
  script:
    - aws s3 sync ./dist s3://stg-${APP_NAME} --delete --only-show-errors --cache-control max-age=180
    - aws cloudfront create-invalidation --distribution-id ${TEST_CLOUDFRONT_ID} --paths "/*"
  dependencies:
    - test_build_app
  rules:
    - if: $CI_COMMIT_BRANCH == "qa"

# ========================================
# LIVE (master branch)
# ========================================

live_build_app:
  extends: .node_base
  stage: build_app
  script:
    - bun install --frozen-lockfile
    - bun run build
  artifacts:
    paths: ['dist/']
    when: on_success
    expire_in: '3 mos'
  rules:
    - if: $CI_COMMIT_BRANCH == "master"

live_deploy_app:
  extends: .deploy_base
  script:
    - aws s3 sync ./dist s3://live-${APP_NAME} --delete --only-show-errors --cache-control max-age=180
    - aws cloudfront create-invalidation --distribution-id ${LIVE_CLOUDFRONT_ID} --paths "/*"
  dependencies:
    - live_build_app
  rules:
    - if: $CI_COMMIT_BRANCH == "master"

MR Pipeline Flow (proposed)

Developer tạo MR → develop

┌─── quality (song song ~2-3 min) ─────────────────────────┐
│ lint │ format │ style │ type-check │ circular │ test     │
│  ✅  │   ✅   │  ✅   │     ✅     │    ✅    │   ✅    │
└──────────────────────────────────────────────────────────┘
                            ↓
┌─── build_app (~1-2 min) ────────────────────────────────┐
│                  merge_build_app ✅                       │
└─────────────────────────────────────────────────────────┘
                            ↓
                   Pipeline: ✅ passed
                   MR: Ready to merge ✅

So sánh: Current vs Proposed

Cost-Benefit Analysis

Extra CI time:    ~2 min parallel quality checks
Extra CI cost:    ~6 jobs × ~2 min each (nhưng song song → ~2 min wall time)

vs

Risk avoided:
  - Unformatted code in develop    ← caught by format:check
  - Lint errors in production      ← caught by lint
  - CSS issues                     ← caught by stylelint
  - Type errors                    ← caught by type-check
  - Circular imports               ← caught by circular
  - Broken features                ← caught by test

2 phút CI thêm >> giờ đồng debug production issues.

Part 4: AWS Integration — S3, CloudFront, ECR

Deployment Architecture

graph LR
    A["GitLab CI<br/>build job"] -->|"artifacts: dist/"| B["GitLab CI<br/>deploy job"]
    B -->|"aws s3 sync"| C["S3 Bucket<br/>{env}-feel-free"]
    B -->|"create-invalidation"| D["CloudFront<br/>CDN cache reset"]
    C --> D
    D -->|"Edge locations"| E["🌍 Users"]

S3 Deployment — What Happens

# Step 1: Sync local dist/ to S3 (upload changed, delete removed)
aws s3 sync ./dist s3://my-feel-free \
  --delete \               # Xóa files trên S3 không có trong dist/
  --only-show-errors \     # Giảm noise trong CI logs
  --cache-control max-age=180  # Browser cache 3 phút

S3 Bucket Structure (after deploy)

s3://my-feel-free/
├── index.html              ← SPA entry point
├── robots.txt
├── sitemap.xml
├── favicon/
├── fonts/
├── images/
├── videos/
└── assets/
    ├── index-a1b2c3d4.js   ← Vite content-hashed bundles
    ├── index-e5f6g7h8.css
    └── vendor-i9j0k1l2.js

CloudFront Cache Invalidation

# Xóa toàn bộ cached files trên CDN
aws cloudfront create-invalidation \
  --distribution-id XXX-XXX-XXX \
  --paths "/*"

# "/*" = invalidate tất cả paths
# → Edge locations worldwide sẽ fetch files mới từ S3 origin
# → Chi phí: $0.005/path (but "/*" counts as 1 path)

Tại sao cần invalidation?

Không invalidate:
  User request → CloudFront edge → cached old index.html ← ❌ Stale

Có invalidation:
  User request → CloudFront edge → cache MISS → fetch from S3 → new index.html ← ✅ Fresh

ECR (Elastic Container Registry)

Real World CI dùng custom Docker image lưu trên GitLab Container Registry:

registry-gitlab.com/feel-free/node:22.14.0-slim

Được build từ project Dockerfile:

FROM node:22.14.0-slim
RUN apt-get update && \
    apt-get upgrade -y && \
    apt-get install -y --no-install-recommends bash git openssh-client jq curl && \
    rm -rf /var/lib/apt/lists/* && \
    npm install -g bun

Khi nào update image?

• Node.js version upgrade → build & push new image
• Bun version upgrade → build & push new image
• Thêm system dependencies → build & push new image

Part 5: Best Practices & Common Pitfalls

✅ Best Practices

1. Pipeline Design

2. Cache Strategy

# ✅ GOOD — Cache theo lockfile, only pull cho non-build jobs
cache:
  key:
    files: [bun.lock]
  paths: [node_modules]
  policy: pull          # Quality/test jobs: chỉ đọc

# ✅ GOOD — pull-push cho build job (cập nhật cache)
dev_build_app:
  cache:
    policy: pull-push   # Build job: đọc + ghi cache

# ❌ BAD — untracked: true (cache quá nhiều)
cache:
  untracked: true       # Tất cả untracked files → bloat

# ❌ BAD — Không dùng cache key files
cache:
  key: "fixed-key"      # Không invalidate khi dependencies thay đổi

3. Artifacts

# ✅ Chỉ pass cần thiết
artifacts:
  paths: ["dist/"]
  expire_in: "3 mos"    # Tự xóa sau 3 tháng

# ✅ Test reports — hiển thị trong MR UI
artifacts:
  when: always           # Upload kể cả test fail
  reports:
    junit: stg-report.xml

4. Security

5. Performance

❌ Common Pitfalls

1. Cache không invalidate

# ❌ Fixed cache key — dependencies thay đổi nhưng cache cũ
cache:
  key: "my-cache"
  paths: [node_modules]

# ✅ Cache key theo lockfile — tự invalidate khi deps thay đổi
cache:
  key:
    files: [bun.lock]
  paths: [node_modules]

2. Artifacts quá lớn hoặc quá lâu

# ❌ Giữ artifacts mãi mãi → tốn storage
artifacts:
  paths: ["dist/"]
  # no expire_in → default instance setting

# ✅ Expire hợp lý
artifacts:
  paths: ["dist/"]
  expire_in: "3 mos"

3. Dùng only/except thay vì rules

# ❌ Legacy — không linh hoạt
only:
  - develop
  - merge_request

# ✅ Modern — kết hợp nhiều conditions
rules:
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  - if: $CI_COMMIT_BRANCH == "develop"

4. Copy-paste jobs cho từng env

# ❌ 3 build jobs giống nhau 90%
dev_build_app:
  image: node:22-slim
  script: ...
test_build_app:
  image: node:22-slim    # ← lặp lại
  script: ...
live_build_app:
  image: node:22-slim    # ← lặp lại
  script: ...

# ✅ Template + extends
.build_base:
  image: node:22-slim
  script: ...

dev_build_app:
  extends: .build_base
  variables: { MODE: development }

5. Không dùng --frozen-lockfile

# ❌ CI có thể modify lockfile → inconsistent builds
script:
  - bun install

# ✅ Exact versions, fail nếu lockfile out of sync
script:
  - bun install --frozen-lockfile

6. Deploy secrets trong script (visible in logs)

# ❌ Secret có thể leak trong logs
script:
  - echo "Deploying with key $AWS_ACCESS_KEY_ID"
# ✅ Dùng masked variables + không echo
# Settings > CI/CD > Variables > Masked ☑️

7. Không test trước deploy

# ❌ Build → Deploy (no validation)
stages:
  - build
  - deploy

# ✅ Quality → Build → Deploy
stages:
  - quality
  - build
  - deploy

8. Wildcard CloudFront invalidation cho mọi deploy

# ⚠️ Invalidate "/*" xóa toàn bộ cache → tất cả users phải re-download
aws cloudfront create-invalidation --paths "/*"

# 💡 Tối ưu hơn: chỉ invalidate index.html
# (vì assets có content hash, URL thay đổi khi content thay đổi)
aws cloudfront create-invalidation --paths "/index.html" "/robots.txt" "/sitemap.xml"

Part 6: Giải thích chi tiết — Các khái niệm dễ nhầm lẫn

🎯 Tổng hợp những khái niệm thường gây confuse khi học GitLab CI/CD, giải thích bằng ví dụ thực tế từ Real World.

1. Cache vs Artifacts — Tại sao cần cả hai?

Khác biệt cốt lõi

Artifacts = "Bưu kiện gửi giữa các stages TRONG 1 pipeline"
Cache     = "Kho đồ giữ lại giữa các PIPELINES khác nhau"

Timeline minh họa:

Pipeline #100 (Monday):
  build_job:
    → bun install (tải packages 30s)
    → bun run build
    → artifacts: dist/        ← Gói dist/ gửi cho deploy_job
    → cache: node_modules/    ← Lưu node_modules/ vào kho

  deploy_job:
    → Nhận dist/ từ artifacts ← Dùng artifacts từ build_job
    → aws s3 sync ./dist

Pipeline #101 (Tuesday):
  build_job:
    → cache: node_modules/    ← Lấy từ kho (skip bun install ~30s!)
    → bun install              ← Chỉ install packages mới (nếu có)
    → bun run build
    → artifacts: dist/

Tại sao không dùng artifacts cho tất cả?

Tại sao cache là “best-effort”?

1. Runner khác nhau → cache không share (trừ khi dùng distributed cache như S3)
2. Cache có thể bị xóa bởi admin hoặc khi runner cleanup
3. Cache key thay đổi (ví dụ bun.lock thay đổi) → cache cũ bị bỏ

Kết luận:

• dist/ → Artifacts (build → deploy PHẢI có, không thể thiếu)
• node_modules/ → Cache (có thì nhanh hơn, không có thì bun install lại — chạy chậm hơn nhưng vẫn đúng)

2. needs — Chạy sớm, phá vỡ stage order?

Vấn đề: Stage order quá cứng nhắc

Mặc định: Tất cả jobs trong stage 1 phải XONG HẾT → stage 2 mới bắt đầu.

stages:
  - quality
  - build

lint: # stage: quality — chạy 20s
format: # stage: quality — chạy 10s
type_check: # stage: quality — chạy 60s ← chậm nhất!
build: # stage: build  — PHẢI ĐỢI type_check xong (60s)

Timeline KHÔNG có needs:
0s -------- 10s ------- 20s ------- 60s ------- 90s
|-- format --|
|------ lint ---------|
|------------ type_check ------------|
                                      |---- build ----|
                                      ↑
                                      Đợi type_check xong!

needs giải quyết bằng DAG

build:
  stage: build
  needs: [] # ← Chạy NGAY, không đợi bất kỳ job nào!

Timeline CÓ needs: []:
0s -------- 10s ------- 20s ------- 30s ------- 60s
|-- format --|
|------ lint ---------|
|------------ type_check ------------|
|------------ build ----------------| ← Chạy song song!

Tiết kiệm: 60s → 0s wait time cho build job.

needs: [] vs needs: [job_name] vs không có needs

Khi nào dùng needs?

• ✅ Quality checks → không phụ thuộc nhau, dùng needs: [] chạy song song
• ✅ Build job → không cần đợi quality (chạy song song, merge chỉ khi cả 2 pass)
• ⚠️ Deploy → needs: [build_job] vì cần artifacts từ build
• ❌ không dùng needs cho jobs có dependency thực sự (deploy cần build output)

3. when — Khi nào job chạy?

5 giá trị của when

when: on_success   # (default) Chạy khi TẤT CẢ previous jobs thành công
when: on_failure   # Chạy khi CÓ ÍT NHẤT 1 previous job FAIL
when: always       # LUÔN chạy, bất kể success hay fail
when: manual       # Tạo nút bấm ▶️ trên GitLab UI, phải click thủ công
when: delayed      # Chạy sau 1 khoảng thời gian

Ví dụ thực tế

# ① on_success — Mặc định, đa số jobs
build:
  script: bun run build
  when: on_success # Chỉ build nếu quality checks pass

# ② on_failure — Notification khi fail
notify_slack:
  script: curl $SLACK_WEBHOOK -d '{"text":"Pipeline FAILED!"}'
  when: on_failure # Chỉ gửi Slack khi có lỗi

# ③ always — Cleanup, luôn chạy
cleanup:
  script: rm -rf /tmp/build-*
  when: always # Dù pass hay fail đều dọn dẹp

# ④ manual — Deploy production cần click thủ công
deploy_production:
  script: deploy.sh
  when: manual # ▶️ Button trên UI, phải click mới chạy
  # Pipeline vẫn "passed" dù job manual chưa chạy

# ⑤ delayed — Chờ 1 lúc rồi chạy
delayed_cleanup:
  script: cleanup.sh
  when: delayed
  start_in: 30 minutes # Chạy sau 30 phút

when trong rules vs when ngoài rules

# ⚠️ when trong rules — quyết định ĐIỀU KIỆN chạy
job:
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
      when: manual        # Master → phải click thủ công
    - if: $CI_COMMIT_BRANCH == "develop"
      when: on_success    # Develop → tự động chạy
    - when: never         # Còn lại → không chạy

# when ngoài rules — không kết hợp được với rules
job:
  when: always  # ← Nếu dùng rules thì when ở đây bị IGNORE
  rules:        # Rules đã bao gồm when logic
    - ...

4. allow_failure: true — Có retry không?

allow_failure là gì?

job:
  allow_failure: true
  retry: 2
  script:
    - bun run lint

Hành vi:

1. Job chạy → fail
2. retry: 2 → CÓ retry, chạy lại tối đa 2 lần
3. Nếu retry vẫn fail → job hiện ⚠️ (warning, màu vàng)
4. Pipeline vẫn passed ✅ (vì allow_failure: true)

So sánh

📌 retry và allow_failure là 2 cơ chế độc lập. retry quyết định “có thử lại không”, allow_failure quyết định “fail thì pipeline sao”.

Use case thực tế

# Lint check — nên pass nhưng không block deploy
lint:
  allow_failure: true # Warning nếu fail
  retry: 0 # Không retry, lint fail = code issue, retry không fix được

# Flaky test — đôi khi fail do timing
e2e_test:
  allow_failure: false # Phải pass
  retry: 2 # Retry vì có thể flaky

# External service check — có thể down
security_scan:
  allow_failure: true # Không block pipeline
  retry: 1 # Retry 1 lần phòng transient error

5. environment vs variables — Khác nhau hoàn toàn

environment — Đánh dấu deployment target

deploy_dev:
  environment:
    name: development # Tên environment
    url: https://dev.feel-free.com # URL truy cập
  script: deploy.sh

environment KHÔNG phải biến. Nó là metadata cho GitLab UI:

1. Operations > Environments → hiển thị danh sách environments
2. Mỗi environment → lịch sử deploy, link URL, nút Rollback
3. Review Apps → tạo environment tạm cho mỗi MR

GitLab UI > Operate > Environments:
┌─────────────────────────────────────────────────┐
│ Environment  │ Last deploy  │ Status  │ URL     │
│──────────────│──────────────│─────────│─────────│
│ production   │ 2h ago       │ ✅      │ 🔗      │
│ development  │ 30m ago      │ ✅      │ 🔗      │
│ review/mr-42 │ 1d ago       │ stopped │ 🔗      │
└─────────────────────────────────────────────────┘

variables — Biến dùng trong script

deploy_dev:
  variables:
    S3_BUCKET: my-feel-free # Dùng trong script
    CLOUDFRONT_ID: XXX-XXX-XXX # Dùng trong script
  script:
    - aws s3 sync ./dist s3://${S3_BUCKET} # ← variables dùng ở đây
    - aws cloudfront create-invalidation --distribution-id ${CLOUDFRONT_ID}

Kết hợp cả hai

deploy_dev:
  environment: # ← Cho GitLab UI tracking
    name: development
    url: https://dev.feel-free.com
  variables: # ← Cho script execution
    S3_BUCKET: my-feel-free
    CLOUDFRONT_ID: XXX-XXX-XXX
  script:
    - aws s3 sync ./dist s3://${S3_BUCKET}

📌 environment = UI tracking & deployment management. variables = giá trị inject vào script.

6. Cache tăng tốc giữa các pipelines — Ví dụ cụ thể

Không có cache

Pipeline #1 (Monday 10:00):
  build_job:
    bun install  → 45s (download TẤT CẢ packages)
    bun run build → 30s
    Total: 75s

Pipeline #2 (Monday 14:00): (chỉ thay đổi 1 file .tsx)
  build_job:
    bun install  → 45s (download TẤT CẢ packages LẠI!)  ← Lãng phí
    bun run build → 30s
    Total: 75s

Pipeline #3 (Tuesday 09:00): (thêm 1 package mới)
  build_job:
    bun install  → 45s (download TẤT CẢ packages LẠI!)  ← Lãng phí
    bun run build → 30s
    Total: 75s

3 pipelines × 45s = 135s wasted trên bun install.

Có cache

build_job:
  cache:
    key:
      files: [bun.lock] # Cache key = hash(bun.lock)
    paths: [node_modules] # Cache node_modules/
    policy: pull-push # Download cache + Upload cache sau khi xong

Pipeline #1 (Monday 10:00):
  build_job:
    cache: MISS (lần đầu, chưa có)
    bun install  → 45s
    cache: UPLOAD node_modules/ (hash: abc123)
    Total: 45s + upload time

Pipeline #2 (Monday 14:00): (bun.lock KHÔNG đổi → same hash)
  build_job:
    cache: HIT ✅ (hash abc123 → download node_modules/)
    bun install  → 2s (nothing to install!)  ← Tiết kiệm 43s!
    Total: 2s

Pipeline #3 (Tuesday 09:00): (thêm package → bun.lock đổi → hash mới)
  build_job:
    cache: MISS (hash def456, chưa có)
    bun install  → 10s (có sẵn node_modules, chỉ install package mới)
    cache: UPLOAD node_modules/ (hash: def456)
    Total: 10s

Tổng: 75s → 57s. Càng nhiều pipelines, càng tiết kiệm.

Cache policy

# pull-push (default) — Download + Upload
# Dùng cho: job chính (build ở develop/master)
build:
  cache:
    policy: pull-push

# pull — Chỉ Download, KHÔNG upload
# Dùng cho: MR jobs (không muốn MR pollute cache)
merge_build:
  cache:
    policy: pull

# push — Chỉ Upload, KHÔNG download
# Dùng cho: scheduled job chuyên tạo cache (ít dùng)
warm_cache:
  cache:
    policy: push

7. Hidden Jobs & Templates — Có thể override?

Hidden job = template, bắt đầu bằng dấu chấm (.)

.node_template:
  image: node:22-slim
  tags:
    - runner-linux
  cache:
    key:
      files: [bun.lock]
    paths: [node_modules]
    policy: pull
  retry: 1

extends — Kế thừa VÀ override

lint:
  extends: .node_template # Kế thừa image, tags, cache, retry
  stage: quality
  script:
    - bun run lint # Thêm script (template không có)
  retry: 0 # ⬆️ OVERRIDE retry từ 1 → 0

Kết quả merge:

# GitLab merge .node_template + lint → job cuối cùng:
lint:
  image: node:22-slim # ← từ template
  tags: [runner-linux] # ← từ template
  cache: # ← từ template
    key:
      files: [bun.lock]
    paths: [node_modules]
    policy: pull
  retry: 0 # ← OVERRIDE từ job (0 thay vì 1)
  stage: quality # ← từ job
  script: [bun run lint] # ← từ job

Override rules cho extends

.template:
  variables:
    A: '1'
    B: '2'

job:
  extends: .template
  variables:
    B: 'overridden' # Override B
    C: '3' # Thêm C


# Kết quả:
# variables: { A: "1", B: "overridden", C: "3" }  ← Hash → deep merge

Multi-level extends

.base:
  tags: [linux]

.node:
  extends: .base # Kế thừa .base
  image: node:22-slim

lint:
  extends: .node # Kế thừa .node → cũng có .base
  script: bun run lint
# Kết quả lint:
# tags: [linux]           ← từ .base
# image: node:22-slim     ← từ .node
# script: [bun run lint]  ← từ lint

8. YAML Anchors — Cơ chế tái sử dụng của YAML

YAML Anchors là gì?

Anchors là tính năng của YAML (không phải GitLab). Cho phép define 1 block rồi reference lại nhiều chỗ.

# & = define anchor (đặt tên)
# * = reference anchor (gọi lại)
# << = merge key (merge hash/object)

Ví dụ cơ bản

# ① Define anchor
.default_cache: &default_cache
  key:
    files: [bun.lock]
  paths: [node_modules]
  policy: pull

# ② Reference — dùng nguyên
job1:
  cache: *default_cache
  # → key: { files: [bun.lock] }, paths: [node_modules], policy: pull

# ③ Reference + Override — dùng << merge key
job2:
  cache:
    <<: *default_cache # Merge tất cả từ anchor
    policy: pull-push # Override policy


# Kết quả job2.cache:
# key: { files: [bun.lock] }, paths: [node_modules], policy: pull-push

Anchors vs extends

Thực tế trong Real World

# ✅ Dùng anchor cho 1 block (cache)
.default_cache: &default_cache
  key:
    files: [bun.lock]
  paths: [node_modules]

# ✅ Dùng extends cho job template
.node_template:
  image: registry-feel-free.com/.../node:22.14.0-slim
  tags: [runner-linux]
  cache:
    <<: *default_cache # Anchor cho cache
    policy: pull

lint:
  extends: .node_template # extends cho job
  script: bun run lint

9. Không có needs: [] thì sao?

So sánh 3 tình huống

stages:
  - quality
  - build

# Job ở stage: quality
lint:
  stage: quality
  script: bun run lint
format:
  stage: quality
  script: bun run format:check
type_check:
  stage: quality
  script: bun run type-check # ← Chạy 60s

Tình huống A: build KHÔNG có needs (mặc định)

build:
  stage: build
  script: bun run build

quality stage: lint(20s) + format(10s) + type_check(60s) ← SONG SONG
                                                          ↓
                                            Đợi TẤT CẢ xong (60s)
build stage:                                              build(30s)
Total: 60s + 30s = 90s

Tình huống B: build có needs: []

build:
  stage: build
  needs: [] # ← Chạy ngay!
  script: bun run build

quality stage: lint(20s) + format(10s) + type_check(60s)
build stage:   build(30s)  ← Chạy SONG SONG với quality!
Total: max(60s, 30s) = 60s    ← Tiết kiệm 30s

Tình huống C: build có needs: [lint]

build:
  stage: build
  needs: [lint] # ← Chỉ đợi lint xong
  script: bun run build

lint(20s) → build(30s)           Total: 50s
format(10s) ──→ (done)
type_check(60s) ────────→ (done)
Total: max(60s, 50s) = 60s

📌 Không có needs = đợi TOÀN BỘ stage trước. Đây là hành vi mặc định và thường không phải vấn đề với pipeline đơn giản. Chỉ cần needs khi muốn tối ưu thời gian.

10. rules:changes vs trigger/triggers — Hai thứ khác nhau hoàn toàn

rules:changes — “Chạy job này khi file thay đổi”

lint:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - src/**/*.{ts,tsx} # Chỉ lint khi source code thay đổi
        - eslint.config.js # Hoặc config ESLint thay đổi

Mục đích: Skip job nếu file không liên quan thay đổi → tiết kiệm CI time.

trigger — “Job này trigger pipeline CON”

# Parent pipeline (.gitlab-ci.yml)
trigger_frontend:
  trigger:
    include: frontend/.gitlab-ci.yml # ← Tạo CHILD pipeline
  rules:
    - changes:
        - frontend/**/* # Chỉ trigger khi frontend thay đổi

Mục đích: Tách pipeline lớn thành nhiều pipeline nhỏ (monorepo pattern).

So sánh

Real World có cần trigger?

Không. Real World là single repo (chỉ frontend). Dùng rules:changes trong job là đủ.

trigger hữu ích khi:

• Monorepo có frontend/, backend/, shared/ → mỗi folder trigger pipeline riêng
• Cần decouple pipeline phức tạp thành nhiều pipeline con

11. Masked Variables — echo $SECRET không hiển thị?

Masked là gì?

Khi tạo variable ở Settings > CI/CD > Variables, có option Mask variable:

Variable:  AWS_SECRET_ACCESS_KEY
Value:     XXX-XXX-XXX/XXX-XXX-XXX/XXX-XXX-XXX
☑️ Masked    → Giá trị bị ẩn trong job logs
☑️ Protected → Chỉ available ở protected branches

Hành vi khi masked

script:
  - echo "Key is: $AWS_SECRET_ACCESS_KEY"
  # Job log hiển thị: Key is: [MASKED]

  - echo $AWS_SECRET_ACCESS_KEY | base64
  # Job log: [MASKED]  ← Vẫn bị mask!

  - export MY_VAR=$AWS_SECRET_ACCESS_KEY
  - echo $MY_VAR
  # Job log: [MASKED]  ← Mask theo VALUE, không phải tên biến

Cơ chế hoạt động

GitLab tìm kiếm giá trị (value) trong output và thay thế bằng [MASKED]:

Output trước mask: "Key is: XXX-XXX-XXX/XXX-XXX-XXX/XXX-XXX-XXX"
GitLab tìm: "XXX-XXX-XXX/XXX-XXX-XXX/XXX-XXX-XXX"
Output sau mask:  "Key is: [MASKED]"

Giới hạn của Mask

# ⚠️ Mask KHÔNG bảo vệ 100%
script:
  # ❌ Chia nhỏ giá trị → mask không nhận ra
  - echo ${AWS_SECRET_ACCESS_KEY:0:10} # Hiện 10 ký tự đầu!

  # ❌ Ghi ra file rồi cat → mask không nhận ra
  - echo $AWS_SECRET_ACCESS_KEY > /tmp/secret.txt
  - cat /tmp/secret.txt # Có thể hiện!

  # ❌ Encode → mask không nhận ra dạng encoded
  - echo $AWS_SECRET_ACCESS_KEY | rev # Hiện ngược!

📌 Mask là “best-effort” text replacement trong logs. Nó KHÔNG phải encryption. Secret vẫn available trong container. Masked chỉ giúp tránh vô tình leak trong logs.

Requirements cho masked variables

Giá trị phải:

• Ít nhất 8 ký tự
• Không chứa newline (\n)
• Chỉ chứa characters trong Base64 alphabet (trường hợp chuẩn)

12. resource_group — Cùng project hay across projects?

Vấn đề: 2 deploy jobs chạy đồng thời

Scenario: Developer A push commit → Pipeline #100 → deploy_production
          Developer B push commit → Pipeline #101 → deploy_production

Kết quả: CẢ HAI deploy chạy cùng lúc!
  Pipeline #100: aws s3 sync (đang upload)
  Pipeline #101: aws s3 sync (cũng upload) ← CONFLICT!

resource_group giải quyết

deploy_production:
  resource_group: production # ← Lock: chỉ 1 job tại 1 thời điểm
  script: aws s3 sync ./dist s3://live-feel-free

Pipeline #100: deploy_production → 🔒 Lock "production" → chạy
Pipeline #101: deploy_production → ⏳ Đợi lock... (queued)
                                   → Pipeline #100 xong
                                   → 🔒 Lock "production" → chạy

Scope: Cùng project

resource_group scope là per-project. Nghĩa là:

• ✅ 2 pipelines cùng project → bị lock (đợi nhau)
• ❌ 2 pipelines khác project → KHÔNG bị lock (independent)

Tại sao CÓ THỂ có 2 pipelines cùng project?

Scenario 1: Developer A push → Pipeline #100
             Developer B push (vài giây sau) → Pipeline #101
             → 2 pipelines chạy song song trong cùng project!

Scenario 2: Merge to master → Pipeline triggered
             Schedule nightly → Pipeline triggered
             → 2 pipelines cùng lúc!

Scenario 3: Manual retry Pipeline #99
             New push → Pipeline #100
             → 2 pipelines cùng lúc!

Process mode

deploy:
  resource_group: production
  # Mặc định: process_mode = oldest_first (FIFO)

📌 Đối với deploy, oldest_first (default) là hợp lý. Nếu muốn chỉ deploy commit mới nhất, dùng newest_first kết hợp interruptible.

13. untracked: true — Cache untracked files?

Untracked files là gì?

# Files mà git KHÔNG track (không trong .gitignore, chưa git add)
git status
  Untracked files:
    node_modules/      ← untracked (trong .gitignore)
    dist/              ← untracked (trong .gitignore)
    temp-debug.log     ← untracked (quên add)

Nhưng trong CI context, untracked: true nghĩa là cache tất cả files mà git chưa track trong working directory.

Ví dụ từ Real World hiện tại

dev_build_app:
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules # ← Cache node_modules (explicit)
    untracked: true # ← THÊM: Cache TẤT CẢ untracked files

untracked: true cache những gì?

Sau khi bun install + bun run build:

Working directory:
  src/           ← tracked (git)
  package.json   ← tracked (git)
  node_modules/  ← untracked ✅ (cached vì untracked: true)
  dist/          ← untracked ✅ (cached vì untracked: true)  ⚠️ KHÔNG CẦN!
  .bun/install/  ← untracked ✅ (cached)
  *.tmp          ← untracked ✅ (cached)  ⚠️ KHÔNG CẦN!

Vấn đề

# ⚠️ untracked: true → cache NHIỀU HƠN cần thiết
# dist/ (build output) → không cần cache, đã có artifacts
# .tmp files → rác, tăng cache size
# → Cache bloat, upload/download chậm hơn

# ✅ Tốt hơn: chỉ cache paths cụ thể
cache:
  key:
    files: [bun.lock]
  paths:
    - node_modules # Chỉ cache node_modules
  # KHÔNG dùng untracked: true

📌 untracked: true = cache mọi thứ git không track. Thường gây bloat. Nên dùng paths: chỉ định cụ thể thay vì untracked: true.

14. Dockerfile — Custom Image vs Public Image

Real World Dockerfile hiện tại

FROM node:22.14.0-slim

RUN apt-get update && \
  apt-get upgrade -y && \
  apt-get install -y --no-install-recommends \
  bash \
  git \
  openssh-client \
  jq \
  curl && \
  rm -rf /var/lib/apt/lists/* && \
  npm install -g bun

Tại sao dùng custom image thay vì public image?

Public image (node:22-slim):
  ❌ Không có bun → mỗi CI job phải: npm install -g bun (30s)
  ❌ Không có git → gitlab runner cần git để clone repo
  ❌ Không có jq  → script parse JSON cần jq

Custom image (đã cài sẵn):
  ✅ bun đã có → skip install (0s)
  ✅ git, openssh, jq, curl đã có → sẵn sàng chạy
  ✅ Mỗi pipeline tiết kiệm 30-60s install time
  ✅ Đảm bảo version consistency (mọi job dùng cùng bun version)

Khi nào cần update image?

slim vs alpine vs full

node:22.14.0 (full/default):
  Size: ~1 GB
  Base: Debian Bookworm
  Có:  build-essential, python3, gcc, make,...
  Use: Khi cần compile native modules (node-gyp, sharp)

node:22.14.0-slim:
  Size: ~200 MB  ← Real World dùng này
  Base: Debian Bookworm (stripped)
  Có:  Minimal packages
  Use: Đa số projects (không cần compile tools)

node:22.14.0-alpine:
  Size: ~130 MB
  Base: Alpine Linux (musl libc)
  Có:  Minimal (dùng apk thay apt)
  Use: Image nhỏ nhất, nhưng CÓ THỂ không tương thích với một số packages

node:22.14.0-bookworm:
  = node:22.14.0 (full) — explicit Debian version name

Tại sao Real World chọn slim thay vì alpine?

slim (Debian):
  ✅ glibc → tương thích với hầu hết npm packages
  ✅ apt-get → quen thuộc, packages phong phú
  ✅ Ít bug liên quan đến libc
  ❌ Lớn hơn alpine ~70MB

alpine (Alpine):
  ✅ Nhỏ nhất (~130MB)
  ⚠️ musl libc → một số native packages KHÔNG tương thích
  ⚠️ DNS resolution khác (musl vs glibc) → có thể gây lỗi
  ⚠️ Date/time handling khác → timezone issues
  ❌ Debug khó hơn (ít tools)

Vulnerabilities & Security

1. So sánh Docker Hub: node:22.14.0-slim vs node:22.22.2-slim

Real World đã upgrade base image từ 22.14.0-slim → 22.22.2-slim. Dữ liệu từ Docker Hub (Docker Scout):

Chi tiết vulnerabilities đáng chú ý trên 22.14.0-slim:

Kết luận: Upgrade từ 22.14.0-slim → 22.22.2-slim giảm 80% vulnerabilities, loại bỏ hoàn toàn Critical, và giảm High từ 19 → 1. Đây là lý do chính cho việc rebuild custom Docker image.

📸 Screenshots Docker Hub: xem public/images/node:22.14.0-slim.png và public/images/node:22.22.2-slim.png

2. Scan vulnerabilities:

# Dùng Docker Scout hoặc Trivy
docker scout cves registry-feel-free.com/.../node:22.14.0-slim
trivy image registry-feel-free.com/.../node:22.14.0-slim

2. Best practices cho security:

# ✅ Pin exact version (không dùng :latest)
FROM node:22.14.0-slim

# ✅ apt-get upgrade -y (update security patches)
RUN apt-get update && apt-get upgrade -y

# ✅ --no-install-recommends (chỉ install cần thiết)
RUN apt-get install -y --no-install-recommends bash git

# ✅ Cleanup apt cache (giảm size + attack surface)
RUN rm -rf /var/lib/apt/lists/*

# ✅ Scheduled rebuild (monthly hoặc khi có CVE)
# CI/CD schedule: rebuild image không chờ code change

3. Monitoring & Update strategy:

Monthly check:
  1. docker scout cves → list vulnerabilities
  2. Nếu có HIGH/CRITICAL → update base image
  3. Rebuild + push → registry
  4. Update .gitlab-ci.yml image reference

Automated (nâng cao):
  - Renovate/Dependabot cho Dockerfile
  - Scheduled pipeline rebuild image hàng tuần
  - Snyk/Trivy scan trong CI pipeline

📌 Custom image = tradeoff. Nhanh hơn per-job, nhưng cần maintain (update, scan vulnerabilities). Luôn pin exact version và schedule regular rebuilds.

15. bun ci vs bun install --frozen-lockfile — Install trong CI/CD

Vấn đề: bun install trong CI có gì sai?

# Developer A chạy bun install → tạo bun.lock → commit
# Developer B pull code → bun install → có thể resolve version KHÁC
# CI pipeline chạy bun install → có thể resolve version KHÁC NỮA

bun install (không có flag):

1. Đọc package.json — tìm dependencies với semver range (ví dụ "react": "^19.0.0")
2. Nếu có bun.lock → dùng versions đã lock
3. NHƯNG nếu package.json đổi (thêm/sửa dependency) mà chưa update bun.lock → resolve version mới + UPDATE lockfile
4. Kết quả: lockfile có thể bị thay đổi trong CI → build không reproducible

--frozen-lockfile giải quyết bằng cách “đóng băng”

bun install --frozen-lockfile
# Tương đương với:
bun ci

Hành vi:

1. Đọc bun.lock (đã commit trong repo)
2. Install chính xác versions đã lock — không resolve mới
3. Nếu package.json không khớp với bun.lock → EXIT WITH ERROR ❌
4. KHÔNG BAO GIỜ thay đổi bun.lock

So sánh

bun ci = bun install --frozen-lockfile

Theo Bun docs:

“For CI/CD environments that want to enforce reproducible builds, use bun ci to fail the build if the package.json is out of sync with the lockfile. This is equivalent to bun install --frozen-lockfile.”

Hai lệnh hoàn toàn giống nhau. bun ci là shorthand dễ nhớ hơn cho CI context.

Yêu cầu để dùng --frozen-lockfile

1. bun.lock phải được commit vào git (đã có trong Real World ✅)
2. package.json phải khớp với bun.lock — nếu developer thêm package mà quên chạy bun install để update lockfile → CI fail
3. bun.lockb (binary, legacy) — nếu project vẫn dùng thì nên migrate sang bun.lock (text-based, bun >= 1.2)

Tại sao quan trọng trong CI/CD?

Scenario KHÔNG có frozen-lockfile:
  1. Developer commit package.json (thêm package) nhưng QUÊN update bun.lock
  2. CI chạy `bun install` → resolve version mới → install OK → build OK
  3. Production deploy version mà CHƯA TỪNG được test locally
  4. Bug chỉ xảy ra ở production! 😱

Scenario CÓ frozen-lockfile:
  1. Developer commit package.json (thêm package) nhưng QUÊN update bun.lock
  2. CI chạy `bun install --frozen-lockfile` → MISMATCH → ❌ FAIL
  3. Developer biết ngay: "Ồ, quên chạy bun install để update lockfile"
  4. Fix → commit lại → CI pass → an toàn ✅

📌 Luôn dùng bun install --frozen-lockfile (hoặc bun ci) trong CI/CD. Đây là best practice từ Bun docs và GitLab Pipeline Security.

16. GitLab CI Cache — Deep Dive (Real Pipeline Observations)

MR Pipeline lần đầu: Tại sao cache MISS?

Từ screenshots MR !20 (Pipeline #1233456), job quality:format log cho thấy:

Restoring cache
Checking cache for 0_bun-randomUUID-non_protected...
WARNING: file does not exist
Failed to extract cache

Giải thích từng dòng:

Tại sao MISS? Đây là lần đầu tiên pipeline chạy với key này:

1. MR branch mới → chưa bao giờ có pipeline cho branch này
2. Quality jobs dùng policy: pull → chỉ đọc cache, không bao giờ tạo cache
3. dev_build_app (có policy: pull-push) chưa chạy vì MR pipeline không trigger develop branch
4. Kết quả: KHÔNG có cache → bun install --frozen-lockfile phải download tất cả 1116 packages

”Not uploading cache due to policy” — Điều này đúng!

Saving cache for successful job
Not uploading cache 0_bun-123...-non_protected due to policy

Đây là hành vi đúng và mong muốn:

# .quality_base extends .node_base, mà .node_base có:
.node_base:
  cache:
    policy: pull # ← Chỉ đọc (download) cache, KHÔNG ghi (upload)

policy: pull = read-only. Job sẽ:

1. ✅ Cố gắng download cache (nếu có) → tiết kiệm bun install time
2. ❌ Không upload cache sau khi xong → không pollute cache

Tại sao quality jobs nên dùng pull?

• 5 quality jobs chạy song song → nếu tất cả pull-push, 5 jobs upload cùng lúc → lãng phí bandwidth
• MR branches không nên tạo cache cho tất cả runner → giữ cache sạch cho develop/protected branches
• Quality jobs install packages chỉ để check (lint, format, type-check) → không cần share kết quả install

Cache Flow: Ai tạo cache? Ai dùng cache?

┌─────────────────────────────────────────────────────────────────┐
│                    CACHE LIFECYCLE                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ① develop branch push                                          │
│     └─ dev_build_app (policy: pull-push)                        │
│        ├─ TRY download cache (key = hash(bun.lock))            │
│        ├─ bun ci (install packages)                             │
│        ├─ bun run build                                         │
│        └─ UPLOAD node_modules/ as cache ← ✅ TẠO CACHE         │
│                                                                 │
│  ② MR pipeline (tiếp theo)                                      │
│     ├─ quality:lint     (policy: pull) → download cache ✅ HIT  │
│     ├─ quality:format   (policy: pull) → download cache ✅ HIT  │
│     ├─ quality:style    (policy: pull) → download cache ✅ HIT  │
│     ├─ quality:type-check (policy: pull) → download cache ✅ HIT│
│     ├─ quality:circular (policy: pull) → download cache ✅ HIT  │
│     └─ merge_build_app  (policy: pull) → download cache ✅ HIT  │
│                                                                 │
│  ③ Nếu bun.lock thay đổi → hash mới → cache MISS lại          │
│     └─ Chờ dev_build_app chạy lại để tạo cache mới             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

⚠️ Lưu ý quan trọng: Cache scope chia theo protected vs non_protected. Nếu develop là protected branch, cache key sẽ có suffix -protected, trong khi MR branch có suffix -non_protected. Hai scope này KHÔNG share cache với nhau (mặc định). Để MR jobs hưởng cache từ develop, cần tắt “Use separate caches for protected branches” trong Settings > CI/CD > General pipelines, hoặc dùng fallback_keys.

Cache Key Mechanism — Chi tiết

cache:
  key:
    files:
      - bun.lock # ← GitLab hash nội dung file này
  paths:
    - node_modules # ← Folder sẽ được zip và lưu

Quá trình tạo cache key:

1. GitLab đọc file bun.lock từ repo
2. Tính SHA-1 hash: sha1(content of bun.lock) → randomUUID
3. Thêm prefix: 0_bun- (index + tên file không extension)
4. Thêm suffix: -protected hoặc -non_protected (dựa trên branch protection)
5. Cache key cuối cùng: 0_bun-randomUUID-non_protected

Khi nào cache key thay đổi?

Cache Policy — So sánh chi tiết

Cache Storage — Kubernetes Autoscale Runner

Real World dùng runner runner-linux (Kubernetes executor, autoscale):

Runner #1234 (AfFS223) gitlabce-runner-gitlab-runner-AfFS223-fmvxq

Với Kubernetes executor:

• Cache mặc định lưu trong container → mất khi container bị xóa → autoscale = container mới mỗi lần
• Distributed cache (S3/GCS/MinIO) cần được cấu hình bởi admin để cache persist qua các jobs
• Nếu KHÔNG có distributed cache → mỗi job đều cache MISS (vì mỗi job chạy trên container mới)

📌 Kiểm tra với team DevOps: Runner có cấu hình distributed cache (S3 hoặc MinIO) không? Nếu không, cache sẽ không bao giờ hit trên autoscale runner, và bun install phải chạy từ đầu mỗi lần.

Bun install KHÔNG có cache — Có chậm không?

Từ screenshot: 1116 packages installed [1.73s] — cực nhanh!

So sánh:

Bun cực nhanh nhờ:

• Viết bằng Zig (compiled language) thay vì JavaScript
• Global cache binary (không extract node_modules từng file)
• Parallel network requests + parallel file I/O
• Hardlinks thay vì copy files

📌 Với bun, cache là “nice to have” chứ không phải “must have”. Nếu distributed cache chưa được cấu hình, 1.73s cho fresh install là hoàn toàn chấp nhận được. Cache chủ yếu hữu ích cho npm/yarn projects (tiết kiệm 30-50s).

5 Quality Jobs Song Song — Có conflict cache không?

Từ screenshot 3: tất cả 5 quality jobs chạy song song trong 28s.

Không có cache conflict vì:

1. Tất cả dùng policy: pull → không ai upload → không ai overwrite
2. Tất cả dùng cùng cache key → nếu cache tồn tại, tất cả download cùng file
3. Mỗi job chạy trong container riêng biệt → node_modules/ được extract riêng, không share

Nếu dùng pull-push cho tất cả? (KHÔNG nên, nhưng giả sử):

• 5 jobs đồng thời upload → “last write wins” → cache archive bị overwrite nhiều lần
• Không gây lỗi, nhưng lãng phí bandwidth upload 5 lần

17. Deploy Scripts — Giải thích từng dòng

Deploy Job trong pipeline hiện tại

.deploy_base:
  stage: deploy_app
  image: docker.com/alpine:latest
  tags:
    - runner-linux
  before_script:
    - apk add --update bash py-pip
    - pip install awscli --upgrade --user --break-system-packages
    - export PATH=/root/.local/bin:$PATH
  when: on_success

before_script — Cài đặt AWS CLI

Dòng 1: apk add --update bash py-pip

apk add --update bash py-pip
│       │        │    │
│       │        │    └── py-pip: Python package manager (pip)
│       │        └── bash: Bash shell (Alpine mặc định dùng ash/sh)
│       └── --update: update danh sách packages trước khi install
└── apk: Alpine Package Keeper (package manager của Alpine Linux)

Tại sao dùng Alpine? Deploy job không cần Node.js — chỉ cần AWS CLI. Alpine nhỏ gọn (~5MB base image) → pull nhanh, ít CVEs.

Dòng 2: pip install awscli --upgrade --user --break-system-packages

pip install awscli --upgrade --user --break-system-packages
│           │       │         │      │
│           │       │         │      └── --break-system-packages: cho phép pip install
│           │       │         │          bên ngoài venv (Alpine 3.21+ yêu cầu flag này)
│           │       │         └── --user: install vào ~/.local/ thay vì system-wide
│           │       └── --upgrade: nếu đã có thì upgrade lên version mới nhất
│           └── awscli: AWS Command Line Interface
└── pip: Python package installer

AWS CLI v1 được install qua pip. AWS CLI v2 yêu cầu installer riêng (không có trên Alpine nhẹ).

Dòng 3: export PATH=/root/.local/bin:$PATH

export PATH=/root/.local/bin:$PATH
│      │    │                 │
│      │    │                 └── $PATH: giữ lại PATH hiện tại
│      │    └── /root/.local/bin: nơi pip --user install binaries
│      └── PATH: biến môi trường chỉ đường cho shell tìm executables
└── export: đẩy biến ra environment (các commands sau đều thấy)

Sau dòng này, aws command khả dụng:

which aws  # → /root/.local/bin/aws
aws --version  # → aws-cli/1.x.x Python/3.x.x Linux/...

script — Deploy commands (ví dụ: dev_deploy_app)

dev_deploy_app:
  extends: .deploy_base
  before_script:
    - echo "[DEV] ${APP_NAME} deploy start" # ⚠️ override .deploy_base before_script!
  script:
    - aws s3 rm s3://my-${APP_NAME} --recursive --only-show-errors
    - aws s3 cp ./dist s3://my-${APP_NAME} --recursive --only-show-errors --cache-control max-age=180
    - aws cloudfront create-invalidation --distribution-id ${DEV_CLOUDFRONT_ID} --paths "/*"

⚠️ Quan trọng: dev_deploy_app có before_script riêng (chỉ echo) → override hoàn toàn before_script từ .deploy_base! Điều này có nghĩa AWS CLI KHÔNG được install trong dev_deploy_app. Pipeline chỉ pass nếu aws đã có sẵn trong environment từ trước (ví dụ: CI variables, pre-configured runner, hoặc custom deploy image).

Dòng 1: aws s3 rm — Xóa toàn bộ S3 bucket content

aws s3 rm s3://my-feel-free --recursive --only-show-errors
│   │  │  │                            │           │
│   │  │  │                            │           └── --only-show-errors: chỉ hiện lỗi
│   │  │  │                            │               (giảm noise trong CI log)
│   │  │  │                            └── --recursive: xóa TẤT CẢ files/folders trong bucket
│   │  │  └── s3://my-feel-free: S3 bucket URL
│   │  └── rm: remove (xóa)
│   └── s3: S3 high-level commands
└── aws: AWS CLI

Tại sao xóa trước? Đảm bảo no stale files. Nếu build mới không còn file old-page.html nhưng S3 vẫn có → user có thể truy cập file đã bị xóa.

Dòng 2: aws s3 cp — Upload toàn bộ dist/ lên S3

aws s3 cp ./dist s3://my-feel-free --recursive --only-show-errors --cache-control max-age=180
│   │  │  │      │                            │           │                  │
│   │  │  │      │                            │           │                  └── --cache-control max-age=180
│   │  │  │      │                            │           │                      Browser cache 180 giây (3 phút)
│   │  │  │      │                            │           └── --only-show-errors
│   │  │  │      │                            └── --recursive: upload tất cả files
│   │  │  │      └── s3://...: destination bucket
│   │  │  └── ./dist: source folder (build artifacts)
│   │  └── cp: copy
│   └── s3
└── aws

--cache-control max-age=180: Browser sẽ cache files 3 phút. Sau 3 phút → browser sẽ re-validate với server. Đây là balance giữa performance (ít requests) và freshness (user thấy bản mới nhanh).

Dòng 3: aws cloudfront create-invalidation — Xóa CDN cache

aws cloudfront create-invalidation --distribution-id XXX-XXX-XXX --paths "/*"
│   │           │                   │                                 │
│   │           │                   │                                 └── --paths "/*"
│   │           │                   │                                     Invalidate TẤT CẢ paths
│   │           │                   └── --distribution-id: CloudFront distribution ID
│   │           └── create-invalidation: yêu cầu CloudFront xóa cached content
│   └── cloudfront: CloudFront service
└── aws

Tại sao cần invalidation?

• CloudFront cache files ở edge locations worldwide (Tokyo, Seoul, Singapore…)
• Không invalidate → user nhận file cũ từ edge server gần nhất
• /* = invalidate tất cả → chi phí $0.005 (coi như 1 path, rất rẻ)
• Edge servers sẽ fetch lại từ S3 origin khi có request tiếp theo

s3 rm + s3 cp vs s3 sync --delete — So sánh

Pipeline hiện tại dùng rm + cp (2 bước). Có thể thay bằng sync --delete (1 bước):

# Cách hiện tại (2 bước):
aws s3 rm s3://bucket --recursive         # Xóa TOÀN BỘ
aws s3 cp ./dist s3://bucket --recursive  # Upload TOÀN BỘ

# Cách tối ưu (1 bước):
aws s3 sync ./dist s3://bucket --delete   # Chỉ upload files THAY ĐỔI, xóa files thừa

IAM Permissions cần cho S3 + CloudFront

Deploy job cần IAM user/role với các permissions sau:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3Deploy",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::my-feel-free",
        "arn:aws:s3:::my-feel-free/*",
        "arn:aws:s3:::stg-feel-free",
        "arn:aws:s3:::stg-feel-free/*",
        "arn:aws:s3:::live-feel-free",
        "arn:aws:s3:::live-feel-free/*"
      ]
    },
    {
      "Sid": "CloudFrontInvalidation",
      "Effect": "Allow",
      "Action": "cloudfront:CreateInvalidation",
      "Resource": "arn:aws:cloudfront::ACCOUNT_ID:distribution/*"
    }
  ]
}

Giải thích permissions:

📌 sync --delete cần thêm s3:GetObject để so sánh ETag/size giữa local và remote. Nếu đổi từ rm+cp sang sync, đảm bảo IAM policy có permission này.

AWS Credentials trong GitLab CI

# Old pipeline (backup) — credentials trong script:
script:
  - export AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
  - export AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
# New pipeline — credentials TỰ ĐỘNG từ CI/CD Variables
# (Settings > CI/CD > Variables > AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# GitLab inject vào environment → KHÔNG CẦN export trong script

GitLab CI variables được inject tự động vào environment. Hai dòng export trong backup là không cần thiết (but harmless). Pipeline mới đã loại bỏ chúng.

18. Pipeline Behavior trên MR — Quan sát thực tế

Pipeline #1582455 — MR !355

Từ screenshots, pipeline cho MR chore/upgrade-vite-pipeline:

┌─── Stage: quality ────────────────────────────────────────────┐
│ quality:circular  ✅  │ Tất cả 5 jobs chạy SONG SONG          │
│ quality:format    ✅  │ Duration: 28s (max of all 5 jobs)      │
│ quality:lint      ✅  │ Runner: #7190 (Kubernetes autoscale)   │
│ quality:style     ✅  │ Source: Merge Request Event             │
│ quality:type-check ✅ │ Cache: MISS (first run, pull policy)   │
└───────────────────────────────────────────────────────────────┘
                        ↓ (all passed)
┌─── Stage: build_app ─────────────────────────────────────────┐
│ merge_build_app   ✅  │ Build only (no artifacts for deploy)  │
│                       │ Chỉ chạy khi MR event                 │
└───────────────────────────────────────────────────────────────┘
                        ↓
          deploy_app: SKIPPED (MR → không deploy)

Observations & Key Takeaways

1. Kubernetes runner details:

Running with gitlab-runner 15.6.1 (133d7e76)
Using Kubernetes namespace: gitlabce-runner
Image: registry-gitlab.com/feel-free/node:22.12.2-slim

• Runner version: 15.6.1 (khá cũ — latest stable khoảng 17.x)
• Kubernetes executor: mỗi job = 1 pod riêng
• Pod lifecycle: Pending → ContainersNotReady → Running → Completed

2. Git shallow clone:

Fetching changes with git depth set to 20...
Checking out ed886f4b as refs/merge-requests/355/head...

• git depth 20: chỉ fetch 20 commits gần nhất → nhanh hơn
• Checkout refs/merge-requests/355/head: GitLab tự tạo ref cho mỗi MR

3. bun ci thực tế chạy gì:

$ bun install --frozen-lockfile          ← bun ci = bun install --frozen-lockfile
bun install v1.3.11 (af24e281)
$ bun run clean:sass-dts                 ← postinstall script
$ rimraf --glob "src/**/*.module.scss.d.ts"
$ husky                                  ← postinstall script
+ @commitlint/cli@19.8.1
+ @eslint/js@9.30.1
... (1116 packages)
1116 packages installed [1.73s]

• bun ci = alias cho bun install --frozen-lockfile
• Postinstall scripts (clean:sass-dts, husky) chạy tự động
• 1.73s cho 1116 packages — bun cực nhanh

4. Thời gian chi tiết job quality:format:

Phần lớn thời gian là Kubernetes pod startup (chờ container sẵn sàng), không phải bun install hay format check.

19. Cache Best Practices — Tối ưu cho Real World Pipeline

Vấn đề hiện tại

Pipeline hiện tại có 3 vấn đề về cache:

Tại sao pipeline cũ chỉ có cache ở develop?

Nhìn vào .gitlab-ci.backup.yml:

# ✅ dev_build_app — CÓ cache
dev_build_app:
  cache:
    key:
      files: [bun.lock, bun.lockb]
    paths: [node_modules]
    policy: pull-push
    untracked: true # ← Cũ: cache cả untracked files (không nên)

# ❌ test_build_app — KHÔNG có cache
test_build_app:
  # ... không có cache block

# ❌ live_build_app — KHÔNG có cache
live_build_app:
  # ... không có cache block

Lý do:

1. Frequency: develop chạy nhiều nhất (mỗi PR merge) → benefit từ cache lớn nhất
2. Protected scope isolation: qa/master là protected → cache scope -protected riêng, develop cache không dùng được
3. Bun speed: 1-2s install → người viết pipeline thấy không đáng thêm cache config cho qa/master
4. Risk vs reward: Cache trên production pipeline (master) thêm complexity nhưng tiết kiệm ít thời gian

Best Practice #1: Dùng cache:unprotect để share cache cross-scope

Vấn đề cốt lõi: dev_build_app (trên develop = protected branch) tạo cache với suffix -protected. MR jobs (non_protected) tìm cache với suffix -non_protected. Hai scope không share với nhau mặc định.

Lỗi phổ biến: Nghĩ rằng fallback_keys giải quyết được vấn đề cross-scope. KHÔNG ĐÚNG.

Từ GitLab docs:

“If the Use separate caches for protected branches setting is enabled, per-cache fallback keys are appended with -protected or -non_protected”

Nghĩa là fallback_keys CŨNG bị scope — chúng chỉ giải quyết MISS trong cùng scope, không cross-scope:

MR job (non_protected) với fallback_keys: [bun-develop]:
  Primary:  0_bun-{hash}-non_protected  → MISS
  Fallback: bun-develop-non_protected   → cũng MISS! (không ai tạo key này)

  develop (protected) đã tạo: 0_bun-{hash}-protected  ← khác scope, không thấy được

Giải pháp đúng — cache:unprotect: true:

# dev_build_app: VIẾT vào cache không có scope suffix
dev_build_app:
  extends: .node_base
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull-push
    unprotect: true # ← key lưu là "0_bun-{hash}" (KHÔNG có -protected)

# .node_base: ĐỌC từ cùng unscoped cache
.node_base:
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull # ← READ ONLY → an toàn, không thể ghi
    unprotect: true # ← tìm "0_bun-{hash}" (cùng key format) → HIT!

Tại sao an toàn? — Deep dive vào “read and write”

GitLab docs viết:

“When set to true, users without access to protected branches can read and write to cache keys used by protected branches.”

Đọc qua thì có vẻ nguy hiểm — MR branch có thể ghi vào cache của protected branch? Nhưng cần hiểu: unprotect và policy là 2 layer độc lập:

• unprotect: true = xóa rào cản scope — protected/non_protected branches nhìn thấy cùng cache key
• policy: pull = chặn upload — runner không bao giờ ghi cache khi job kết thúc

Kết hợp:

• unprotect: true + policy: pull = “Tôi nhìn thấy cache chung, nhưng chỉ đọc, không thể ghi” ✅
• unprotect: true + policy: pull-push = “Tôi nhìn thấy cache chung, VÀ có thể ghi” ⚠️

Security analysis cho pipeline hiện tại:

Kết luận: Chỉ dev_build_app có thể ghi (pull-push), và job đó chỉ chạy trên develop (protected branch, kiểm soát bởi merge rules). Tất cả MR jobs dùng policy: pull → không thể poison cache dù unprotect: true.

Lưu ý bảo mật bổ sung:

• GitLab docs cũng cảnh báo: “The cache separation with cache key names is a security feature and should only be disabled in an environment where all users with Developer role are highly trusted.”
• Dùng unprotect: true yêu cầu tin tưởng developer không tự ý đổi policy: pull → pull-push trên MR job. Nhưng thay đổi .gitlab-ci.yml qua MR luôn cần review → rủi ro rất thấp
• Cache poisoning với node_modules ít nguy hiểm hơn so với executable artifacts vì packages đã bị lock bởi bun.lock + --frozen-lockfile

Flow khi unprotect: true:

develop push → dev_build_app:
  key: 0_bun-{hash}   (no suffix!) ← UPLOAD

MR push → quality:lint:
  key: 0_bun-{hash}   (no suffix!) ← DOWNLOAD → HIT! ✅

Khi nào dùng fallback_keys? Chỉ hữu ích trong cùng scope:

# Ví dụ: MR branch mới, cùng bun.lock với develop (cả hai đều non_protected)
.node_base:
  cache:
    key:
      files: [bun.lock]
      prefix: bun
    paths: [node_modules]
    policy: pull
    fallback_keys:
      - bun-$CI_DEFAULT_BRANCH # e.g., bun-develop-non_protected
      - bun-default # bun-default-non_protected (cần ai đó tạo)

Trường hợp này chỉ work nếu develop KHÔNG phải protected branch (hiếm gặp).

Best Practice #2: Tách “cache warmer” job riêng

Pattern: 1 job chuyên tạo cache, các job khác chỉ đọc.

# Job "ẩn" chỉ có nhiệm vụ tạo cache cho quality jobs
prepare:cache:
  extends: .node_base
  stage: .pre # ← Chạy trước tất cả
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
    policy: pull-push # ← Tạo cache
  script:
    - bun ci
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: $CI_COMMIT_BRANCH =~ /^(develop|qa|master)$/

Lợi ích:

• 1 job upload → không có race condition
• Quality jobs song song chỉ pull → nhanh hơn, không phí bandwidth
• Cache được tạo trước khi quality jobs bắt đầu

Nhược điểm:

• Thêm 1 job (~30s) vào pipeline
• Với bun speed (1.73s install), lợi ích không lớn
• Tăng complexity

⚠️ Kết luận: Với bun, “cache warmer” pattern không đáng vì install time chỉ 1-2s. Pattern này hữu ích cho npm/yarn (30-60s install). Giữ approach hiện tại (chỉ dev_build_app dùng pull-push) là đủ tốt cho bun.