Bỏ qua

ADR-0003: Docs-hub deploy lên Cloudflare Pages thay vì GitHub Pages

  • Status: Accepted
  • Date: ~2026-07-20 (backfilled 2026-07-25, theo ngày sửa SERVICES.md/docs-hub)
  • Supersedes: —
  • Superseded by: —

Bối cảnh

Cần 1 nơi tổng hợp docs/ từ nhiều repo (backend-k3s, go-service-k3s, chatbot-service-k3s, gitops...) thành 1 trang docs-hub duy nhất, kể cả repo ở org GitHub khác (UITCoderWarrior100/football-booking-data-pipeline). Toàn bộ repo đang private trên GitHub Free, mà GitHub Pages cho private repo yêu cầu GitHub Pro/Team — không có sẵn trong plan hiện tại.

Quyết định

Deploy docs-hub sang Cloudflare Pages (Direct Upload, project football-booking-k3s-docs-hub) thay vì GitHub Pages. Workflow .github/workflows/docs-hub.yml checkout docs/ từ các repo (kể cả cross-org qua PAT DOCS_HUB_PAT) rồi build/deploy qua Cloudflare API token.

Lựa chọn khác đã cân nhắc

  • Nâng cấp GitHub Pro để dùng GitHub Pages cho private repo: tốn phí hàng tháng chỉ để có 1 tính năng — loại vì mục tiêu chi phí thấp cho dự án cá nhân/thesis.
  • Public hoá repo để dùng GitHub Pages free: lộ toàn bộ source/secret pattern — loại vì lý do bảo mật.
  • Netlify/Vercel: tương đương Cloudflare Pages về free tier, nhưng đã dùng Cloudflare cho R2 (data-pipeline) và Zero Trust Access — gộp về 1 vendor để quản lý token/billing tập trung — chọn Cloudflare.

Hệ quả

  • Được: docs-hub chạy free, không cần nâng cấp GitHub plan; gộp chung ecosystem Cloudflare (Pages + Access + R2).
  • Đánh đổi: thêm 3 secret cần quản lý (DOCS_HUB_PAT, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID); URL *.pages.dev public theo mặc định — cần bật Cloudflare Access (Zero Trust) để không lộ docs nội bộ ra ngoài, đây là bước khuyến nghị nhưng KHÔNG bắt buộc trong SERVICES.md — cần rà lại nếu chưa bật.

Liên kết

  • Docs liên quan: SERVICES.md (mục "Setup docs-hub")