CI/CD của core

Pipeline của monorepo core nằm trong .gitlab-ci.yml ở gốc repo (sửa file này cần core team duyệt theo CODEOWNERS). CI/CD của app sản phẩm là chuyện khác — xem CI/CD & Deploy.

Tổng quan

Job	Stage	Chạy khi	Chặn merge	Việc
quality	quality	Mọi pipeline	Có	Lint, typecheck, test, build, độ phủ tài liệu
ai-review	quality	Nhánh có MR đang mở, đủ biến	Không	Claude Code review diff, đăng comment lên MR
ai-eval	quality	main, hoặc MR đụng packages/ai/**; đủ biến	Không	Chạy eval prompt qua AI gateway
release	release	main	—	Publish package lên registry nếu là commit version
deploy:pages	deploy	main, sau quality	—	Build docs, deploy Cloudflare Pages

Mọi job dùng image node:24, corepack enable rồi pnpm install --frozen-lockfile; thư mục store của pnpm cache theo pnpm-lock.yaml.

quality

pnpm lint
pnpm typecheck
pnpm test
pnpm test:scripts
pnpm exec turbo run build --concurrency=1
node scripts/docs-coverage.mjs --strict
node scripts/check-mcp-links.mjs

Chạy y hệt trên máy trước khi mở MR — trên máy dùng pnpm build cho nhanh. CI build tuần tự (--concurrency=1) vì pod runner giới hạn RAM: build docs và playground chạy song song từng làm job bị kill.

Docs là một workspace package nên cũng qua đủ các bước: lint và typecheck demo, test script sinh trang, build VitePress (báo link hỏng, TSDoc thiếu), rồi docs-coverage kiểm component và runtimeConfig đã có tài liệu, check-mcp-links kiểm link docs mà @tasco/mcp trả cho AI.

Bước fail	Thường do	Xem
lint	Import ant-design-vue ngoài @tasco/ui, quên import type	Quy ước code
typecheck	Sai kiểu; component mới chưa khai trong tasco.d.ts hoặc env.d.ts của docs	Thêm component C*
test	Test đỏ, coverage dưới ngưỡng	Test & coverage
build	d.ts có typeof import(...); export thiếu TSDoc; link docs hỏng; dấu ngoặc nhọn đôi của Vue trong markdown	Viết tài liệu
docs-coverage	Component thiếu trang/mô tả; khoá runtimeConfig mới chưa có trong trang tra cứu	Biến môi trường
check-mcp-links	Đổi cách @tasco/mcp đọc markdown hoặc nâng VitePress làm lệch anchor; trang bị xoá mà dữ liệu cũ còn trỏ tới	MCP & AI review
Job báo runner_system_failure, log cuối có OOMKilled (exit 137)	Pod hết RAM, không phải lỗi code: có bước chạy nhiều build nặng song song. Giữ --concurrency=1 cho build; bước khác bị kill thì hạ --concurrency của bước đó	—

ai-review

Chạy trong branch pipeline khi nhánh có MR đang mở — không tạo pipeline merge_request_event riêng. Job lấy diff từ merge-base với nhánh đích (cắt ở 200KB), mô tả MR, rồi chạy Claude Code headless chỉ với quyền đọc (Read, Grep, Glob) theo prompt .claude/ci-review-prompt.md. Kết quả đăng thành comment "🤖 AI Review" trên MR.

Job allow_failure — review chỉ để tham khảo, người duyệt vẫn quyết. Thiếu biến thì job không chạy. Chi tiết prompt và cách thử: MCP & AI review.

ai-eval

pnpm --filter @tasco/ai eval — chạy bộ case trong packages/ai/evals/cases.ts qua gateway thật, assertion tất định. allow_failure để gateway sập không khoá MR. Script tự thoát 0 khi thiếu biến gateway.

release

1. Ghi thêm registry cấp project và token vào .npmrc (ép https vì CI_API_V4_URL trên instance này là http).
2. node scripts/release-guard.mjs — còn changeset chưa version thì in skip và job kết thúc, không publish.
3. pnpm exec turbo run build --filter="./packages/*" rồi pnpm changeset publish.

Quy trình phát hành và lý do của cổng release-guard: Release.

deploy:pages

pnpm exec turbo run build --filter=docs   # build package docs phụ thuộc, rồi docs/.vitepress/dist (base /v2/)
mkdir -p site/v2 && cp -R docs/.vitepress/dist/. site/v2/
cp docs/deploy/_redirects docs/deploy/versions.json site/
pnpm dlx wrangler@3 pages deploy site --project-name=tasco-web-framework --branch=main

Storybook không deploy: từ GĐ5 của RFC 0003 nó chỉ là công cụ dev cục bộ (pnpm --filter @tasco/ui storybook), còn /storybook/* chuyển hướng về trang Component.

Cloudflare Pages thay toàn bộ site mỗi lần deploy. Khi có bản docs của major cũ, job phải ghép thêm bản đó — xem Release › Tài liệu theo phiên bản.

Biến CI/CD

Settings → CI/CD → Variables. Mọi biến bí mật bật Masked; biến chỉ dùng trên main bật thêm Protected.

Biến	Job	Giá trị
NPM_TOKEN	release	Access token scope write_package_registry (CI_JOB_TOKEN bị 401 khi publish trên instance này)
ANTHROPIC_API_KEY	ai-review	API key Anthropic
GITLAB_REVIEW_TOKEN	ai-review	Project Access Token scope api, role ≥ Reporter — để đăng comment
AI_GATEWAY_URL, AI_GATEWAY_KEY	ai-eval	Gateway OpenAI-compatible và key của nó
AI_EVAL_MODEL	ai-eval	Tuỳ chọn, mặc định claude-haiku-4-5
CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID	deploy:pages	Token quyền Cloudflare Pages: Edit

Biến Protected chỉ có trên nhánh protected: job ở nhánh tính năng không đọc được — đúng như mong muốn với token publish và deploy. Token chứa ký tự $ thì tắt "Expand variable reference".

Thêm hoặc sửa job

• Job không được chặn merge (gọi dịch vụ ngoài, chỉ tham khảo) thì đặt allow_failure: true.
• Job cần biến bí mật: thêm điều kiện biến vào rules để thiếu biến thì job không tạo, thay vì fail.
• Không echo token; cần debug thì in độ dài (${#NPM_TOKEN}) hoặc lọc bỏ dòng token.
• Cập nhật trang này và Git workflow › Biến CI/CD trong cùng MR.

Liên quan

• Release — version MR, pre mode, release-guard.
• Cấu hình .npmrc — registry và token trong CI.
• MCP & AI review — prompt của AI review.