CI/CD với GitHub, GitLab và Bitbucket

Chuẩn bị cấu hình và quyền

Kích hoạt website/backend cần dùng, sao chép Project UUID và Site ID/Service ID từ Dashboard. Cài WhyPik CLI bản mới từ trang tải, dùng Git checkout có origin và nhánh triển khai. Cấu hình phải chỉ rõ tài nguyên; CI không tự chọn tài nguyên mặc định, không bật lại dịch vụ tạm dừng.

Tạo khóa tại Gói & API tài khoản → Tạo API key → Loại key CI/CD · Hosting hoặc CI/CD · Mini Server, chọn đúng dự án và tài nguyên. Bộ sinh dùng secret WHYPIK_HOSTING_DEPLOY_KEY cho Hosting, WHYPIK_API_DEPLOY_KEY cho API; chỉ truyền tên chuẩn WHYPIK_DEPLOY_KEY lúc gọi deploy. Không dùng khóa Admin Database hoặc khóa toàn tài khoản.

Khóa deploy không được gọi Variables API, nhưng được thay mã backend. Mã do pipeline triển khai có thể đọc Variables và dùng danh tính backend. Chỉ cho người được tin cậy sửa source/workflow và truy cập khóa deploy; masking không ngăn mã ứng dụng cố ý gửi secret ra ngoài.

# whypik.toml — thay ba UUID bằng tài nguyên thật của bạn
schema_version = 1
endpoint = "https://app.whypik.com"
project = "PROJECT_UUID"

[targets.api]
service = "SERVICE_UUID"
directory = "api"

[targets.hosting]
site = "SITE_UUID"
directory = "web"
output = "dist"
install = ["npm", "ci"]
build = ["npm", "run", "build"]

Kiểm tra source trước khi sinh pipeline

API cần api/server.py. Hosting npm cần web/package.json, package-lock.json hoặc npm-shrinkwrap.json đã commit, cùng lệnh npm ci/build thật. Chỉ dùng Hosting HTML tĩnh thì bỏ install/build và đặt output trỏ thư mục có index.html. Bộ sinh hiện nhận HTML tĩnh hoặc npm; Yarn/pnpm/Bun và toolchain khác cần tự cấu hình CI, không tự đoán.

Với ví dụ hai target, chạy lệnh bên dưới trong thư mục có whypik.toml. CLI không deploy cả hai khi chỉ chọn một target. Build chạy các argv đã cấu hình, không ghép chuỗi shell; các khóa WhyPik đã biết được bỏ khỏi môi trường tiến trình build. Không đặt secret trong cấu hình, file frontend, dist hoặc biến public của bundler.

whypik build --target hosting --install
whypik run --host 127.0.0.1 --port 8000
# Sau khi thử API, dừng run bằng Ctrl+C.

GitHub Actions

Chạy lệnh bên dưới rồi vào repository → Settings → Secrets and variables → Actions → tạo repository secret WHYPIK_HOSTING_DEPLOY_KEY với khóa website, WHYPIK_API_DEPLOY_KEY với khóa backend. Commit source, whypik.toml và hai workflow. Push main để chạy; Actions → Run workflow cũng chỉ deploy được branch đã chọn.

Sinh .github/workflows/whypik-hosting.yml và whypik-api.yml riêng. Checkout/setup actions ghim commit SHA, Python/Node ghim bản cụ thể, contents:read, chạy Ubuntu. Chỉ bước Deploy nhận secret WhyPik. Checkout giữ credential đọc Git để CLI xác minh HEAD của origin ở repository private. Không cấu hình chạy deploy cho pull_request.

whypik ci init github --target hosting --branch main
whypik ci init github --target api --branch main
git add whypik.toml .github/workflows/whypik-hosting.yml .github/workflows/whypik-api.yml
# Commit source và lockfile cùng workflow, rồi push main.

GitLab CI

Chạy lệnh bên dưới để tạo .gitlab-ci.yml. Trong Settings → CI/CD → Variables, thêm WHYPIK_API_DEPLOY_KEY, bật Masked/Hidden và Protected; bảo vệ branch main để job nhận biến. Muốn triển khai Hosting, đổi --target thành hosting và dùng WHYPIK_HOSTING_DEPLOY_KEY.

Job nhận push hoặc Run pipeline của branch đã chọn, dùng image ghim digest và resource_group riêng tài nguyên. Với Hosting npm, image Node cài Python3/venv trước khi cài CLI. Secret CI cấp cho job vẫn thuộc phạm vi tin cậy của job; không chạy source hoặc script không tin cậy trong job này.

whypik ci init gitlab --target api --branch main
git add whypik.toml .gitlab-ci.yml
# Commit source rồi push main; xem CI/CD → Pipelines.

Bitbucket Pipelines

Bật Pipelines trong repository. Chạy lệnh bên dưới để tạo bitbucket-pipelines.yml. Vào Repository settings → Repository variables, thêm WHYPIK_API_DEPLOY_KEY và bật Secured. Hosting dùng --target hosting và WHYPIK_HOSTING_DEPLOY_KEY.

File chỉ chạy branch đã chọn, dùng image ghim digest và concurrency-group riêng tài nguyên. Giới hạn quyền sửa branch và workflow. Secured ẩn giá trị khỏi giao diện/log chuẩn của provider, không biến mã trong job thành môi trường không thể đọc secret.

whypik ci init bitbucket --target api --branch main
git add whypik.toml bitbucket-pipelines.yml
# Commit source rồi push main; mở Pipelines để xem kết quả.

Repository có nhiều thư mục hoặc đã có CI

Dùng --directory đường/dẫn để trỏ thư mục có whypik.toml. CLI tìm Git root, đặt workflow đúng vị trí tại root và giữ --directory trong các lệnh đã sinh. --branch bắt buộc; --target chỉ nhận hosting/api. Không dùng tên website làm target.

CLI không ghi đè hoặc tự hợp nhất file CI có sẵn. GitLab/Bitbucket có một file CI chính: khi thêm target thứ hai hoặc tích hợp pipeline đang có, hợp nhất job/step có chủ đích, giữ secret/tài nguyên/concurrency riêng và kiểm tra cấu hình trên provider. Có thể sinh ở một Git checkout tạm chưa chứa file CI để tham khảo, rồi lấy phần job cần dùng. Không xóa pipeline đang hoạt động chỉ để chạy lại generator.

CI chạy CLI qua HTTPS/API WhyPik; không cần SSH đến máy chủ WhyPik và không được cấp shell VPS. Trên runner riêng cũng dùng các lệnh CLI này với credential Git và khóa triển khai phù hợp.

whypik ci init github --directory apps/customer --target hosting --branch release/production

Bản CLI, trạng thái và retry

Khi sinh file, CLI đọc manifest công khai và kiểm tra đúng version đang cài. File sinh ghim URL ZIP + SHA256 cụ thể, pip --require-hashes kiểm bytes; lần chạy pipeline không lấy latest. Nếu version không khớp, cập nhật CLI rồi sinh lại trong checkout tạm và review thay đổi pin. ZIP cũ được giữ trên WhyPik. Dependency build của pip và package ứng dụng không tự được ghim bởi checksum ZIP.

CLI kiểm HEAD của local, metadata CI và origin trước deploy. Pipeline của commit cũ trả lỗi; số thứ tự cũ trong cùng repository/workflow/branch bị API từ chối. Provider concurrency giảm chạy chồng, nhưng không thiết lập thứ tự commit giữa các branch/repository khác nhau cùng deploy một tài nguyên.

Chỉ kết thúc exit 0 khi đúng deployment ready và active. Upload được nhận không có nghĩa triển khai thành công. Mất kết nối thì retry cùng lần pipeline dùng cùng receipt và bytes; không tự gửi sang tài nguyên khác. Receipt đã failed cần pipeline mới sau khi sửa nguyên nhân. GitHub Re-run jobs giữ run_number, nên không tạo deployment mới cho receipt failed; push commit mới để có lần chạy mới.

File sinh là điểm khởi đầu có thể chạy sau khi cấu hình UUID, source, khóa và quyền Git đúng. Thêm test/lint riêng của ứng dụng trước bước deploy. Không đưa task nền hoặc migration phá dữ liệu vào pipeline mặc định.

Hosting và Mini Server hỗ trợ tải chia phần. CLI 0.3.0rc2 dùng chunks-v1 cho Mini Server khi API công bố khả năng này; trên máy chủ cũ vẫn dùng multipart. Khi retry cùng lần pipeline, giữ nguyên source, service và deploy key. Mini Server giữ thứ tự phiên bản ngay từ lúc nhận lượt tải, nên lượt cũ hoàn tất sau không tự ghi đè bản mới hơn.

Migration trước deploy: một stage cho mỗi Database

Chỉ opt-in khi môi trường đã mở Migration và whypik.toml có liên kết đúng Database. Thêm --migrations-env LABEL vào generator. Một Database dùng chung nhiều website/backend chỉ có một chuỗi và một stage migration trong release workflow; không chạy một job migration độc lập cho mỗi target.

Pipeline Migration còn yêu cầu --local-bundle là đường dẫn tương đối trong repository tới source bundle WhyPik đầy đủ đã commit (backend, sdk/mini, infra/database-local). Không có bundle tương thích thì generator dừng; không thay local replay bằng comment hoặc check JSON.

Hosting trong pipeline này phải build ra thư mục output riêng bên dưới workspace, khác thư mục chứa whypik.toml. Bước đóng gói chỉ chuyển file website được phép sang artifact, giữ cả .well-known cần cho website và loại credential/state local. Không đặt output là toàn bộ repository hoặc dùng artifact CI để lưu .whypik.

Build/test/local replay chạy trước stage có quyền hosted. GitHub dùng Ubuntu runner có Docker. GitLab cần disposable shell runner riêng tag whypik-local-db; Bitbucket cần disposable self-hosted Linux shell runner labels self.hosted, linux.shell, whypik.local.db. Runner cần Python ≥3.11, Docker Compose ≥2.20 và Node 24 nếu build Hosting. Không dùng lại máy build có mã không tin cậy cho job giữ secret Migration/deploy.

Stage local dùng workspace mới đã kiểm tra, init/doctor/start rồi db replay --env local --yes --approve-policy --approve-destructive --timeout 600. Replay lần lượt từng prefix, tạo backup local đã xác minh trước mỗi bước xóa; EXIT trap dừng stack. Hai flag phê duyệt chỉ nằm ở local replay để kiểm cả lịch sử, không được truyền sang apply hosted.

GitHub tạo .github/workflows/whypik-release.yml; GitLab/Bitbucket dùng file CI chính. Nếu file đã có, CLI từ chối ghi đè: tích hợp các target vào release hiện có có chủ đích, không thêm workflow song song cùng migrate Database.

Tạo secret WHYPIK_MIGRATION_KEY với quyền plan/apply đúng Project và truyền riêng cho stage migration. Khóa build/deploy không tự có quyền Database. Không chạy migration có secret trên PR/fork không tin cậy. Stage hosted mặc định không cấp approve-policy hoặc destructive; các thay đổi này cần review/approval riêng trước release.

Stage chạy validate, plan --env LABEL --out FILE rồi migrate --env LABEL --plan FILE --yes. Chỉ sau exit 0 mới deploy ứng dụng. Lỗi apply hoặc còn đối soát dừng deploy; không tự rollback schema khi deploy ứng dụng lỗi. Với rename/drop, dùng expand/backfill/contract để các bản ứng dụng còn chạy tương thích.

Provider concurrency không thay khóa/fence trên Database. Hai pipeline khác repository/target cùng trỏ Database vẫn phải được server kiểm head/lineage. Đọc plan summary và giữ operation receipt để xử lý timeout; không bật force hoặc sửa artifact plan.

Trước deploy, status --env LABEL --expect-plan FILE đối chiếu lại đích và head với plan đã áp dụng. Bước này không thay thế khóa/fence máy chủ hoặc biến nhiều target thành một giao dịch release. Bộ local đã chạy chuỗi migration mẫu qua Docker trên Linux. Pipeline sinh sẵn vẫn cần nghiệm thu trên GitHub/GitLab/Bitbucket thật; kết quả local không thay thế kết quả provider.

whypik ci init github --target api --branch main --migrations-env staging --local-bundle vendor/whypik-local
# Hoặc chọn đúng provider của repository:
whypik ci init gitlab --target api --branch main --migrations-env staging --local-bundle vendor/whypik-local
whypik ci init bitbucket --target hosting --branch main --migrations-env staging --local-bundle vendor/whypik-local

Tiếp tục tải ZIP Hosting

whypik deploy --target hosting gửi các phần tối đa 8 MiB và chờ ghép/triển khai thành công. Mỗi pipeline giữ mã yêu cầu ổn định; retry cùng pipeline, cùng output sẽ bỏ qua phần đã nhận. Không sửa artifact rồi dùng lại cùng mã.

Khi deploy thủ công gặp lỗi tải, CLI in UUID để thử lại bằng --idempotency-key. Giữ nguyên output và chạy lại trong 48 giờ. Sau khi máy chủ nhận đủ phần, CLI vẫn đợi trạng thái triển khai và active; HTTP 202 không được xem là thành công. Mini Server còn dùng ZIP nguyên file theo hạn mức riêng.

whypik deploy --target hosting --idempotency-key REQUEST_UUID