Môi trường staging và preview cho từng pull request
Để có staging và preview trên ZoCloud: mở menu môi trường trên canvas của project, Tạo environment tên staging sao chép từ production và gắn với nhánh develop; rồi kết nối repo qua GitHub App và bật Preview cho Pull Request để mỗi PR có một bản chạy riêng, địa chỉ riêng, database trống riêng, tự xoá khi PR đóng. Phần dưới hướng dẫn từng bước và gợi ý một quy trình gọn cho team nhỏ.
Vì sao team nhỏ cũng cần staging
Khi chỉ một người code, đẩy thẳng lên production có vẻ nhanh. Từ người thứ hai trở đi (hoặc khi AI agent viết phần lớn code), rủi ro tăng nhanh:
- Thay đổi chưa ai xem đã ra tay khách.
- Migration database chạy thẳng vào dữ liệu thật.
- Người duyệt code phải tự kéo nhánh về máy, cài đặt, chạy thử: mất 15 phút cho mỗi PR, nên thường bị bỏ qua.
Staging và preview giải quyết đúng ba điểm đó: có nơi thử giống production, database tách riêng, và người duyệt chỉ cần bấm một đường link.
Environment trên ZoCloud là gì
Mỗi project mặc định có environment production. Một environment là một bản sao của project: có mạng nội bộ riêng, biến riêng, database riêng (hoặc dùng chung nếu bạn chọn). Các service trong cùng environment gọi nhau qua http://<service>.internal, nên staging không bao giờ gọi nhầm sang API production qua mạng nội bộ.
| Loại | Tên | Sống bao lâu | Theo nhánh |
|---|---|---|---|
| Production | production |
Lâu dài | main |
| Staging | staging (bạn đặt) |
Lâu dài | develop (hoặc nhánh bạn chọn) |
| Preview | pr-<số> |
Tới khi PR đóng hoặc merge | Nhánh của PR |
Tạo môi trường staging
Trên portal
- Mở project, trên canvas bấm menu môi trường (cạnh chữ
production). - Tạo environment:
- Tên:
staging. - Sao chép từ:
production. Environment mới có cùng service, biến và volume. - Nhánh Git:
develop. Để trống nếu muốn giữ nhánh riêng của từng service. - Chọn Database riêng (trống) để có database trống giống bản gốc, không đụng dữ liệu production.
- Tên:
- Từ giờ mỗi lần push lên
developlà staging tự deploy (với repo kết nối qua GitHub App và đã bật Tự deploy khi push).
Nếu không chọn database riêng, environment mới không có database của nó. Biến tham chiếu như ${{pg.DATABASE_URL}} chỉ trỏ tới database cùng environment, nên khi đó bạn phải tự thêm database cho staging.
Bằng zo CLI
zo env create staging -from production -branch develop -fresh-db
zo env # liệt kê environment, * là environment đang gắn
zo link myorg/shop/web@staging # gắn thư mục với service ở staging
zo logs -f # xem log staging
Muốn đẩy thử một bản từ máy vào staging mà không đổi thư mục đang gắn:
zo deploy -env staging
AI agent làm được việc này qua MCP với công cụ create_environment (có tuỳ chọn fresh_databases) và list_environments. Xem tài liệu zo CLI.
Việc cần làm ngay sau khi tạo staging
- Thay khoá: staging sao chép biến và biến chung của production. Đổi khoá thanh toán, khoá gửi e-mail sang khoá test; tạo khoá AI riêng có hạn mức thấp. Xem quản lý biến môi trường an toàn.
- Dữ liệu mẫu: database mới trống. Thêm lệnh seed vào
prestarttrongzocloud.json, hoặc chạy script seed một lần. - Tiết kiệm tài nguyên: staging ít người dùng, có thể bật Ngủ khi không có truy cập (tab Cấu hình) và để 1 bản chạy.
Bật preview cho từng pull request
Preview cần repo kết nối qua GitHub App (mục GitHub của tổ chức → Kết nối GitHub, cài ZoCloud cho repo). ZoCloud chỉ đọc mã nguồn và ghi trạng thái deploy lên commit. Chi tiết ở tài liệu app.
- Menu môi trường → Preview cho Pull Request → Bật preview.
- Chọn database cho preview:
- Database riêng, trống: mỗi PR có bản sao trống của các database production (cùng tên, không có dữ liệu), xoá khi đóng PR. Khuyến nghị.
- Dùng chung database production: nhanh, nhưng code chưa duyệt chạm được dữ liệu thật. Chỉ dùng khi bạn hiểu rõ rủi ro.
- Không có database: cho frontend tĩnh hoặc app chỉ gọi API.
Từ đó, mỗi PR vào nhánh mà project deploy sẽ có:
- environment
pr-<số>riêng, mỗi service chạy 1 bản; - địa chỉ
https://<service>-pr<số>-<project>.zocloud.app; - deploy lại theo mỗi lần push lên nhánh của PR;
- trạng thái "ZoCloud preview / " trên PR, bấm vào mở thẳng bản preview;
- một bình luận trên PR liệt kê địa chỉ và trạng thái từng service, tự cập nhật sau mỗi lần push (cần GitHub App có quyền Pull requests: Read and write; nếu app được cài trước khi có quyền này, chủ tài khoản GitHub cần chấp nhận quyền mới);
- tự xoá khi PR đóng hoặc merge.
Muốn xoá sớm: chọn environment preview → Xóa preview.
Giới hạn cần biết
- PR từ fork không có preview: preview chạy với biến môi trường của project, cho code từ fork chạy là để người lạ đọc được khoá của bạn.
- Preview tính vào giới hạn gói: service và database của preview cộng vào số service, số database, RAM và CPU của tổ chức. Nếu vượt, ZoCloud không tạo preview và báo lý do bằng trạng thái lỗi trên commit.
- Biến chung: preview đọc biến chung của chính nó trước, rồi của environment nó preview.
Quy trình gợi ý cho team 2–10 người
Điều cần nắm trước: preview chỉ được tạo cho PR vào nhánh mà production deploy (thường là main). PR vào develop hay nhánh khác không có preview. Vì vậy quy trình gọn nhất cho team nhỏ là để mọi PR nhắm vào main, còn staging là nơi gom và cho khách xem trước:
feature/xyz ──PR──▶ main ──────────▶ production (tự deploy)
│
├─ preview pr-<số> (tự tạo, tự xoá)
│
└─ push/merge vào nhánh staging ──▶ staging (tự deploy)
- Mỗi việc một nhánh
feature/...từmain. Người viết (hoặc AI agent) mở PR vàomain. - Preview tự lên. Người duyệt bấm link trong bình luận PR, thử tính năng trên database trống, xem log của preview nếu có lỗi.
- Khi cần thử nhiều thay đổi cùng nhau (hoặc cho khách, cho QA xem với dữ liệu mẫu ổn định): merge các nhánh vào nhánh
staging; environmentstaginggắn với nhánh này tự deploy, database của nó giữ dữ liệu qua các lần deploy. - Merge PR vào
main: preview tự xoá, production tự deploy. Bản đang chạy vẫn phục vụ cho tới khi bản mới khoẻ. - Có sự cố: tab Deploy → chọn bản cũ → Quay lại bản này, hoặc
zo rollback <số>. Không cần build lại.
Nếu team quen Git flow với nhánh develop, vẫn làm được: đặt staging theo develop như phần trên, nhưng PR vào develop sẽ không có preview; preview chỉ xuất hiện ở PR develop → main.
Team rất nhỏ (1–2 người) có thể bỏ staging: PR vào main, duyệt trên preview, merge là lên production.
Mẹo làm việc
- Watch paths cho monorepo: ở Build và chạy, đặt
apps/web/**cho service web,apps/api/**cho API, để push sửa tài liệu không kích hoạt deploy. - Thông báo: mục Thông báo của tổ chức gửi sự kiện Deploy thất bại về Slack, Discord hoặc webhook, chọn đúng project.
- Migration: đặt lệnh migration vào
prestarttrongzocloud.json; nó chạy ở preview và staging trước, nên lỗi lộ ra trước khi đụng production. - Agent và preview: để AI agent mở PR thay vì đẩy thẳng lên
main. Bạn duyệt trên preview như duyệt code của người.
Ví dụ zocloud.json cho cả ba môi trường
{
"build": {
"install": "npm ci",
"build": "npm run build",
"watch_paths": ["src/**", "package.json", "!**/*.md"]
},
"deploy": {
"start": "npm start",
"prestart": "npm run migrate",
"health_path": "/health"
}
}
Cùng một file dùng cho production, staging và preview; khác biệt nằm ở biến môi trường của từng environment, không nằm trong code. Giá trị trong zocloud.json được ưu tiên hơn các ô trên portal.
Chi phí của staging và preview
Staging và preview không có giá riêng: chúng dùng tài nguyên trong giới hạn gói của tổ chức. Một project gồm web và API với một PostgreSQL, có staging và trung bình hai PR mở cùng lúc, sẽ dùng khoảng 8 service và 4 database cùng lúc, vượt giới hạn 5 service và 2 database của Hobby, nên phù hợp với gói Pro. Xem bảng tính chi tiết ở bài chạy một app vibe coding mỗi tháng tốn bao nhiêu và tài liệu thanh toán.
Câu hỏi thường gặp
Staging và preview khác nhau thế nào? Staging là một environment lâu dài, theo một nhánh riêng như develop hoặc staging, nơi gom các thay đổi trước khi lên production. Preview là environment tạm cho từng pull request, tự tạo khi mở PR và tự xoá khi PR đóng hoặc merge.
Preview của pull request có dùng database production không? Tuỳ bạn chọn khi bật preview: Database riêng, trống (mỗi PR một bản sao trống, xoá khi đóng PR), Dùng chung database production (nhanh nhưng PR chạm được dữ liệu thật), hoặc không có database. Nên chọn database riêng trống.
Vì sao pull request từ fork không có preview? Preview chạy với biến môi trường của project, gồm cả khoá bí mật. Nếu cho code từ fork chạy preview, người lạ có thể đọc được các khoá đó, nên ZoCloud không tạo preview cho PR từ fork.
Staging và preview có tính vào giới hạn gói không? Có. Service và database của mọi environment, kể cả staging và preview, đều tính vào giới hạn của gói (số service, số database, RAM, CPU). Hãy chọn gói đủ chỗ hoặc dọn các environment không dùng.
Đọc thêm: deploy Node.js với PostgreSQL, cron job và worker nền.