Giao diện
CI/CD của core
Pipeline của monorepo core chạy trên Jenkins, khai báo ở gốc repo (sửa cần core team duyệt theo CODEOWNERS):
Jenkinsfile— job của nhánhmain:quality→release→deploy:pages.Jenkinsfile.mr— job của các nhánh khác:quality.
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 | — | Chưa bật trên Jenkins | Không | Claude Code review diff, đăng comment lên MR |
ai-eval | — | Chưa bật trên Jenkins | 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 chạy trong container node:24 của pod agent Kubernetes, corepack enable rồi pnpm install --frozen-lockfile. Các stage trên main dùng chung một pod nên chỉ cài và build một lần. release lỗi vẫn chạy tiếp deploy:pages.
quality
bash
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
node scripts/check-pack.mjsChạ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-fe/mcp trả cho AI, check-pack kiểm tarball của từng package.
| Bước fail | Thường do | Xem |
|---|---|---|
lint | Import ant-design-vue ngoài @tasco-fe/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-fe/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 |
check-pack | Tarball thiếu file mà exports/main/bin trỏ tới, lọt test/story/.map/.env, chứa host nội bộ, thiếu LICENSE, license khác MIT hoặc access khác public. Bản publish lên npmjs không gỡ được nên lỗi này chặn ở CI | scripts/check-pack.mjs |
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ưa bật trên Jenkins (cần credential ANTHROPIC_API_KEY và GITLAB_REVIEW_TOKEN). Khi bật, 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.
Review chỉ để tham khảo, không chặn merge — người duyệt vẫn quyết. Chi tiết prompt và cách thử: MCP & AI review.
ai-eval
Chưa bật trên Jenkins (cần credential AI_GATEWAY_URL, AI_GATEWAY_KEY). Chạy tay: pnpm --filter @tasco-fe/ai eval — chạy bộ case trong packages/ai/evals/cases.ts qua gateway thật, assertion tất định. Script tự thoát 0 khi thiếu biến gateway.
release
- Ghi token npmjs vào
.npmrc(chỉ trong lúc chạy); xong job trả.npmrcvề như cũ. Không cóNPM_TOKENthì stage fail. node scripts/release-guard.mjs— còn changeset chưa version thì inskipvà job kết thúc, không publish.pnpm exec turbo run build --filter="./packages/*"rồipnpm changeset publish.
Quy trình phát hành và lý do của cổng release-guard: Release.
deploy:pages
bash
./scripts/build-docs-site.sh # /v3/ từ checkout này, /v2/ build từ origin/release/2.x, rồi _redirects + versions.json ở gốc
pnpm dlx wrangler@3 pages deploy site --project-name=tasco-web-framework --branch=mainStorybook không deploy: từ GĐ5 của RFC 0003 nó chỉ là công cụ dev cục bộ (pnpm --filter @tasco-fe/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
Jenkins → Credentials, kiểu Secret text. Jenkins tự che giá trị trong log.
| Credential ID | Biến | Job | Giá trị |
|---|---|---|---|
tasco-web-framework.npm-token.id | NPM_TOKEN | release | Granular access token của npmjs.org, quyền Read and write cho scope @tasco-fe |
tasco-web-framework.cloudflare-api-token.id | CLOUDFLARE_API_TOKEN | deploy:pages | Token quyền Cloudflare Pages: Edit |
tasco-web-framework.cloudflare-account-id.id | CLOUDFLARE_ACCOUNT_ID | deploy:pages | Account ID Cloudflare |
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ì bọc trong
catchError(buildResult: 'SUCCESS', stageResult: 'UNSTABLE'). - Job cần biến bí mật: lấy qua
withCredentials, không ghi giá trị vào file hayenvironment. - Không
echotoken; 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 và publish lên npmjs — token trong CI.
- MCP & AI review — prompt của AI review.