Kế hoạch triển khai CI/CD ¶

Tài liệu này mô tả hiện trạng, lợi ích, và lộ trình đưa CI/CD vào các dự án của Holatech. Phần kỹ thuật dựa trên repo template ci-templates đã hoàn thành ở phiên bản v2.1.0.

1. Vấn đề hiện tại ¶

Việc đưa code lên môi trường chạy đang làm thủ công:

• Tốn thời gian — mỗi lần deploy chiếm hàng giờ của người có kinh nghiệm nhất.
• Hay quên bước — build, chạy migration, cập nhật tag image, restart container; bỏ sót một bước là một sự cố.
• Lỗi phát hiện muộn — nhiều lỗi chỉ lộ ra khi đã ở production, tức là khi khách đã nhìn thấy.
• Phụ thuộc vài người — người đó nghỉ phép thì cả nhóm không phát hành được.

Ba điều đầu đều là hệ quả của điều thứ tư: quy trình nằm trong đầu người, không nằm trong file.

2. CI/CD là gì ¶

Tự động hoá chuỗi: kiểm tra code → chạy test → đóng gói → triển khai. Mỗi khi có thay đổi đẩy lên GitLab, hệ thống tự chạy thay cho con người.

Quy trình được viết thành file .gitlab-ci.yml nằm trong chính repo — nghĩa là nó được review, được version, và ai cũng đọc được.

3. Lợi ích đạt được ¶

4. Môi trường triển khai ¶

Lưu ý về tên gọi. "Local" là máy dev, không có pipeline. "Development" trong tài liệu này là nhánh development — cổng kiểm tra code tự động, không phải một server. Đây là chỗ hay bị hiểu nhầm khi đọc lướt.

Nguyên tắc: build một lần, dùng lại nhiều lần ¶

Production không build lại từ source. Nó gắn tag v1.2.3 lên đúng image đã chạy qua staging.

Lý do: build lại từ cùng một commit vẫn có thể ra kết quả khác (base image đã cập nhật, thư viện có version mới). Nếu build lại, thứ lên production không còn là thứ đã được kiểm tra.

Hệ quả với quy trình: tag phải đặt trên commit đã đi qua nhánh staging. Tag thẳng trên development sẽ bị pipeline chặn kèm thông báo giải thích.

Kho chứa image: GitLab Container Registry, không dùng Docker Hub ¶

Mọi image của sản phẩm nằm trên GitLab Container Registry self-hosted — cùng hệ thống với repo, cùng phân quyền, không phải mua hay đăng ký dịch vụ ngoài.

Docker Hub chỉ còn xuất hiện ở đúng một chỗ: nó là nguồn gốc của các image nền do bên thứ ba phát hành (Node, Alpine…). Ngay cả những image đó ta cũng không tải trực tiếp mà đi qua bộ đệm của GitLab, vì Docker Hub giới hạn 100 lượt tải mỗi 6 giờ theo địa chỉ IP — cả công ty dùng chung một IP nên sẽ đụng trần và mọi pipeline đứng hình cùng lúc.

Registry không để ở chế độ công khai. Server khách tải image bằng deploy token cấp riêng cho từng khách: chỉ quyền đọc, đặt được hạn dùng, và thu hồi được từng cái khi hết hợp đồng. Nếu để công khai thì image — vốn chứa toàn bộ mã nguồn đã biên dịch — ai cũng tải về được, và không có cách nào thu hồi.

Đổi lại, việc tự chạy registry kéo theo ba trách nhiệm vận hành, xem mục 7.

Hai đường đưa image lên máy khách ¶

Mỗi khách một chính sách hạ tầng, template hỗ trợ cả hai:

1. CI SSH thẳng vào server khách — khách cấp deploy key và mở SSH cho IP của runner. Deploy hoàn toàn tự động sau khi bấm duyệt.
2. Khách tự chạy — pipeline sinh sẵn một gói deploy.sh gửi cho khách; khách chạy ./deploy.sh v1.2.3 trên máy họ. Không cần mở SSH, không cần cấp quyền gì trên hạ tầng khách.

Cả hai dùng chung một đoạn script, nên không có chuyện hai đường lệch nhau sau vài tháng.

5. Những gì GitLab làm được — kèm trạng thái thực tế ¶

Ký hiệu: ✅ Có sẵn trong template, dùng được ngay · ⚙️ Cần cấu hình phía GitLab hoặc phía dự án · ⚠️ Chưa có, cần quyết định

Chất lượng code ¶

Bảo mật ¶

Đóng gói & triển khai ¶

Quản trị & phiên bản ¶

Điểm mấu chốt: bản build không đạt sẽ tự động bị chặn ở cổng, không cần ai canh gác thủ công.

6. Phương án triển khai theo giai đoạn ¶

Ước lượng công sức là con số thô để lập kế hoạch, không phải cam kết.

Giai đoạn 0 — Hạ tầng (~1 tuần, admin GitLab) ¶

Phải xong trước, vì mọi giai đoạn sau đều dựa vào.

• Registry của GitLab ra được internet với chứng chỉ TLS thật (Let's Encrypt). Server khách sẽ pull image từ đó. Chứng chỉ tự ký thì mỗi máy khách phải sửa cấu hình Docker — gánh nặng hỗ trợ vĩnh viễn.
• Bật Dependency Proxy cho group. Docker Hub giới hạn 100 lượt tải/6 giờ theo địa chỉ IP; runner của công ty dùng chung một IP nên sẽ đụng trần và cả nhóm đứng hình cùng lúc.
• Bật metadata database cho registry, đặt cleanup policy và lịch garbage collection. Đây là ba việc khác nhau, không phải một — xem mục 7.
• Chuẩn bị runner có Docker-in-Docker.

Xong khi: một dự án thử tải được image từ máy ngoài mạng công ty.

Giai đoạn 1 — Thí điểm một dự án (~3–5 ngày) ¶

Chọn một dự án nhỏ, đang chạy thật nhưng chưa quan trọng bằng các dự án khác.

• Tạo hai nhánh development và staging, đặt Protected branch.
• Copy examples/node-service.gitlab-ci.yml thành .gitlab-ci.yml.
• Bật cổng kiểm tra code: lint, type-check, test, build.
• Bật "Pipelines must succeed" cho merge request.

Xong khi: mở một MR có lỗi lint và thấy nó bị chặn không cho merge.

Giai đoạn 2 — Thêm bảo mật (~1–2 ngày) ¶

• Bật preset security-scan: trivy:fs, gitleaks, commitlint, SAST, Secret Detection.
• Thống nhất cách xử lý khi quét ra lỗ hổng: sửa ngay, hay ghi nhận và hẹn.

Xong khi: thử commit một chuỗi trông giống API key và thấy pipeline chặn lại.

Giai đoạn 3 — Tự động staging (~2–3 ngày) ¶

• Bật preset docker-publish: build image, quét CVE, sinh SBOM.
• Chuẩn bị server công ty: docker-compose.yml dùng biến ${APP_IMAGE}, file .env, và healthcheck trong compose.
• Đặt CI/CD Variables cho staging (xem mục 8).
• Bật deploy:staging.

Xong khi: merge vào staging và thấy bản mới tự lên server công ty trong vài phút, không ai gõ lệnh.

Giai đoạn 4 — Cổng duyệt production (~3–5 ngày) ¶

• Bật docker:release (gắn tag phát hành lên image đã kiểm tra) và release (tạo mục ở trang Releases).
• Chọn đường deploy cho từng khách: CI SSH thẳng, hay gửi gói deploy.sh.
• Cấp deploy token riêng cho từng khách (chỉ quyền đọc registry, có hạn dùng, thu hồi được riêng lẻ).
• Bật deploy:production (bấm tay) và deploy:rollback.
• Diễn tập lùi bản một lần trước khi coi là xong.

Xong khi: phát hành một version thật, và lùi lại được bản trước đó bằng một nút bấm.

Giai đoạn 5 — Nhân rộng (~1 ngày/dự án) ¶

Sau khi thí điểm chạy ổn ít nhất hai tuần.

• Mỗi dự án copy file ví dụ, sửa phần variables, đặt CI/CD Variables.
• Ghim ref vào tag của template — không dùng ref: main, vì một commit vào template có thể làm đỏ pipeline của mọi dự án cùng lúc.
• Viết lại tài liệu bàn giao cho khách (một trang, kèm gói deploy.sh).

7. Việc phía hạ tầng — ba điều dễ bỏ sót ¶

Bỏ Docker Hub và tự chạy registry nghĩa là nhận về ba trách nhiệm. Không làm thì chúng sẽ tự nhắc, vào lúc bất tiện nhất.

1. Cleanup policy KHÔNG giải phóng ổ đĩa. Đây là chỗ dễ hiểu nhầm nhất trong tài liệu GitLab: policy chỉ xoá nhãn, phần dữ liệu bên dưới vẫn nằm nguyên. Muốn lấy lại dung lượng phải chạy garbage collection riêng, và bản thường cần một khoảng thời gian chỉ-đọc. Đặt policy rồi tưởng đã xong thì vài tháng nữa ổ đầy.

2. Bật metadata database nếu muốn dọn dẹp không gián đoạn. Nó là điều kiện của garbage collection online, và của việc nhìn thấy dung lượng từng image. Nhập dữ liệu sau khi registry đã lớn sẽ tốn thời gian chỉ-đọc — làm sớm rẻ hơn.

3. Uptime của GitLab giờ là ràng buộc của khách. GitLab sập hoặc đang nâng cấp thì khách không tải được image, không restart container được, không deploy được. Nếu có khách yêu cầu cam kết dịch vụ cao, cần tính phương án dự phòng.

8. Checklist cho mỗi dự án ¶

Settings → CI/CD → Variables. Đánh dấu Masked cho giá trị bí mật, Protected cho biến chỉ dùng ở nhánh/tag được bảo vệ.

Bẫy hay gặp nhất: biến đánh dấu Protected nhưng nhánh đang chạy chưa được bảo vệ → biến rỗng, job chết ở một chỗ khó hiểu. Pipeline kiểm tra trước và in ra nguyên nhân, nhưng biết trước vẫn đỡ mất thời gian hơn.

Phía server (staging và mỗi máy khách):

• docker + docker compose v2
• docker-compose.yml dùng image: ${APP_IMAGE} — không ghi cứng tag
• healthcheck trong compose. Không có nó thì bước chờ bị bỏ qua, và một container chết lúc khởi động vẫn cho ra pipeline màu xanh
• Đã docker login một lần vào registry bằng deploy token được cấp

9. Rủi ro và điểm chưa xử lý ¶

Cần quyết định: migration cơ sở dữ liệu ¶

Đây là điểm hở duy nhất còn lại, và nó nằm ở chỗ đắt nhất.

Khi deploy hỏng, deploy:rollback đưa image về bản cũ — nhưng schema cơ sở dữ liệu thì đã đổi. Kết quả: code cũ chạy trên schema mới.

Ba hướng, cần chọn một:

Khuyến nghị: làm hướng 1 ngay (viết thành quy ước), thêm hướng 2 ở Giai đoạn 4 trước khi có khách thật lên production.

10. Hiện trạng repo template ¶

Đã hoàn thành, phiên bản v2.1.0:

• 3 preset cắm-là-chạy + thư viện job để dự án lớn tự lắp
• 2 file ví dụ hoàn chỉnh (service đơn, monorepo be/ + fe/)
• Bộ kiểm tra tự động: scripts/check.py (tham chiếu chéo giữa các file) và scripts/test-shell.sh (37 test chạy thử phần shell nhúng trong template, gồm cả gói deploy.sh mà khách sẽ nhận)

Bước còn lại trước khi tag phát hành: chạy ci-lint với CI_LINT_TOKEN để GitLab tự xác nhận cấu hình hợp lệ.