Phần 2 — .gitlab-ci.yml đầu tiên và Variables (predefined, UI, masked)

Series GitLab CI/CD Toàn Tập — 9 phần:

1. Phần 1 — Tổng quan: GitLab CI/CD, kiến trúc và các khái niệm

2. Phần 2 — .gitlab-ci.yml đầu tiên và Variables (predefined, UI, masked) ← bạn đang đọc

3. Phần 3 — Cache vs Artifacts: chiến lược và Reports

4. Phần 4 — Rules và Merge Request Pipelines

5. Phần 5 — GitLab Runner self-hosted: cài đặt và executors (Shell/Docker)

6. Phần 6 — Kubernetes executor: scale runner trên K8s

7. Phần 7 — include, extends, anchors — pipeline modular

8. Phần 8 — Environments, Deployments và Review Apps

9. Phần 9 — Pipeline thực tế Next.js → Docker → K8s + best practices + debug

Mở đầu

Sau khi nắm kiến trúc Pipeline → Stage → Job → Runner → Executor ở Phần 1, phần này ta thực sự viết file .gitlab-ci.yml đầu tiên rồi mở rộng sang hệ thống Variables — phần không thể thiếu khi pipeline cần token, password, image tag động hay region cloud.

1. .gitlab-ci.yml đầu tiên

Tạo file .gitlab-ci.yml ở root repo:

stages:
  - build
  - test
  - deploy

default:
  image: node:20-alpine
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - node_modules/
      - .pnpm-store/

build-job:
  stage: build
  script:
    - corepack enable
    - pnpm install --frozen-lockfile
    - pnpm build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

lint-job:
  stage: test
  script:
    - pnpm install --frozen-lockfile
    - pnpm lint

unit-test-job:
  stage: test
  script:
    - pnpm install --frozen-lockfile
    - pnpm test

deploy-staging:
  stage: deploy
  script:
    - echo "Deploying $CI_COMMIT_SHA to staging"
  only:
    - main

Push lên — pipeline tự chạy: build-job trước, sau đó lint-job và unit-test-job chạy song song, cuối cùng deploy-staging chỉ khi đang ở branch main.

Các khái niệm xuất hiện

• stages: — định nghĩa thứ tự stage. Mặc định là [.pre, build, test, deploy, .post].

• default: — config dùng chung cho mọi job (image, cache, before_script…).

• $CI_COMMIT_REF_SLUG — biến tự động chứa tên branch đã slug-hoá. 100+ biến predefined sẵn dùng.

• artifacts: — file/folder lưu lại để job stage sau download tự động.

• only: [main] — cú pháp cũ; cú pháp mới (mạnh hơn) là rules: (xem mục 5).

2. Variables — tổ chức biến và bí mật

2.1. Predefined variables

GitLab cung cấp ~100 biến tự động — hay dùng nhất:

• $CI_COMMIT_SHA — commit SHA đầy đủ.

• $CI_COMMIT_SHORT_SHA — 8 ký tự đầu.

• $CI_COMMIT_REF_NAME — tên branch/tag.

• $CI_COMMIT_REF_SLUG — version đã slug-hoá (an toàn cho URL/tag).

• $CI_PROJECT_PATH — vd group/subgroup/repo.

• $CI_REGISTRY_IMAGE — URL container registry của project.

• $CI_PIPELINE_SOURCE — push, merge_request_event, schedule, web…

• $CI_JOB_TOKEN — token tạm cho job, dùng login GitLab Container Registry.

2.2. CI/CD Variables (UI)

Vào Settings → CI/CD → Variables. Mỗi biến có 4 flag quan trọng:

• Protected — chỉ truyền cho job chạy trên branch/tag được "protected". Ngăn fork pipeline rò rỉ secret.

• Masked — log tự động ẩn dưới dạng [MASKED]. Yêu cầu giá trị tối thiểu 8 ký tự, đủ độ phức tạp.

• Expanded — expand biến tham chiếu $OTHER_VAR trong giá trị.

• Environment scope — chỉ inject vào job có environment: production…

2.3. Biến cục bộ trong YAML

variables:
  DOCKER_DRIVER: overlay2
  DOCKER_BUILDKIT: "1"
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

build:
  variables:
    NODE_ENV: production
  script:
    - echo "Tag: $IMAGE_TAG"

Biến khai báo ở job override biến global.

Tóm tắt

Trong phần này bạn đã nắm:

• Cấu trúc cơ bản của file: stages, default (image/cache share), job với stage/script/artifacts/only.

• ~100 predefined variables hay dùng: $CI_COMMIT_SHA/SHORT_SHA/REF_NAME/REF_SLUG, $CI_REGISTRY_IMAGE, $CI_PIPELINE_SOURCE, $CI_JOB_TOKEN.

• UI variables có 4 flag quan trọng: Protected (chỉ branch protected), Masked (ẩn trong log, ≥ 8 ký tự), Expanded, Environment scope.

• Biến cục bộ khai báo trong YAML override biến global; biến ở job override biến top-level.

Trong Phần 3, ta phân biệt rõ Cache vs Artifacts — hai khái niệm rất hay bị nhầm — và hệ thống Reports để hiện kết quả test/coverage trực tiếp trong Merge Request.

Phần 3: Cache vs Artifacts: chiến lược và Reports →