* docs: maintenance mode — policy, triage bot, issue forms, status badge, docs for 2.3.0 From v2.3.0 the project takes no new features (CONTRIBUTING.md, in Vietnamese and English). Accepted: scheduled dependency updates; security fixes (High/Critical advisories, runtime vulnerabilities); major language/runtime/framework upgrades; bug fixes including UI/UX and accessibility; language fixes. - .github/workflows/triage.yml + scripts/triage.mjs (unit-tested): an issue or pull request whose title or label asks for a feature is labelled enhancement + out-of-scope, answered in both languages and closed (issues as "not planned"). The owner's items, bots, `maintenance-exception` and anything the owner does are left alone. It runs on pull_request_target but checks out only that one script from the default branch, never a pull request's code; workflow_dispatch is a dry run. - Issue forms: blank issues off, questions and ideas to Discussions, security to the private policy; a new language-problem form; the bug form no longer claims the site's report button fills it (those reports go to a private repository). The pull request template asks which of the five kinds of change it is. - README: a maintenance-mode badge and a Status section; the admin paragraph describes auto-publish. SECURITY.md: High/Critical fixes ship out of schedule; the age-check answer is local storage only. - Docs: decisions D21–D24, maintenance policy and cadence (17 §0, QODANA_TOKEN rotation), roadmap frozen, CI (Qodana, whole-tree licences, triage, merge rules), architecture tree, the Workers Builds deploy command, licence notes without the stale license-checker/GSAP lines. - CHANGELOG [2.3.0]; sonar.projectVersion 2.3.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: link #138 in the 2.3.0 changelog Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs: album labels come from both language entries Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(ci): triage without a checkout, and linear title patterns SonarCloud and Qodana on #139: - githubactions:S7631 flags any checkout in a pull_request_target workflow, even of the default branch. The workflow now reads scripts/triage.mjs from the default branch through the API and imports it from a data: URL — nothing is checked out at all. - javascript:S8786: `\s+a?\s*` let two quantifiers compete for the same spaces. The title is trimmed once and the patterns are written so no two quantifiers overlap. - Qodana RegExpRedundantEscape: the bot check is `endsWith("[bot]")`, no regex. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
10 KiB
08 — CI/CD
0. Thực tế đang chạy (10/2026, v2.0) — §1–§5 bên dưới là kế hoạch ban đầu (lịch sử)
- Deploy: Cloudflare Workers Builds nối repo (không có job deploy trong GitHub Actions):
main→ build +npx wrangler deploy; nhánh khác →npx wrangler versions upload(version preview, không nhận traffic). Cấu hình chi tiết + bẫy đã gặp:07§9. ci.yml(PR, pushmain,workflow_dispatch), jobbuild(timeout 30 phút, checkout kèm submodule):npm ci --ignore-scripts→check-install-scripts→wrangler types(site + widgets) → prettier → eslint →astro check(TS 6) →typecheckbằng TypeScript 7 (intsc -v, kiểm site + widgets) → knip →test:coverage(node:test, ngưỡng 80% dòng, xuấtcoverage/lcov.info) →npm audit --omit=dev --audit-level=high→gen-notices --check→check-exif --changed→ build (+ OG, Pagefind,check-csp-hashes) → smoke test (npm run smoke: chạy worker đã build bằngwrangler dev, kiểm trang/304/HEAD//media//ext-img/admin 403/frame-ancestors, pha ép bật cổng Turnstile kể cả cookie sai định dạng, pha denylist) → cổng trợ năng (từ v2.2.0:npm run previewchạy nền rồinpm run test:a11y— Playwright lái Chrome có sẵn trên runner, không tải trình duyệt; axe-core quét mọi trang trong sitemap của bản build, một trang mỗi template ở theme sáng và bề rộng điện thoại, và menu/tìm kiếm/lightbox/hộp báo lỗi/bảng Aa/bảng pháp lý khi đang mở; sau đó là test bàn phím, reflow 320/360/390px vàforced-colors) → upload coverage làm artifact. Checkbuildlà bắt buộc (rulesetmain), nên PR có vi phạm axe không merge được.- Job
sonarcloud(saubuild; chạy cho pushmainvà PR cùng repo, bỏ qua Dependabot): tải coverage →SonarSource/sonarqube-scan-action(pin SHA) vớisonar-project.properties; trên PR chờ quality gate ("Sonar way" cho new code: coverage ≥ 80%, trùng lặp ≤ 3%, rating A, hotspot đã review). Automatic analysis trên SonarCloud tắt (CI analysis thay thế);SONAR_TOKENlà secret của repo..svelte/.astrokhông được Sonar phân tích — logic quan trọng nằm trong.tsđể đo được. - CodeQL (default setup, repo public) · Snyk (GitHub app) ·
osv-scanner.yml(reusable workflow v2.7.0, SARIF, hằng tuần + khi đổi lockfile) ·lighthouse.yml(treosh/lighthouse-ci-actionpin SHA, preset mobile, chỉ cảnh báo). content-bump.yml(từ v2.3.0 admin tự gọi sau mỗi lần lưu/xoá; nút Xuất bản còn lại để chạy lại;concurrencygộp các lần gọi dồn dập): trỏ submodulesrc/contentvềcontent/main, commit lên nhánhcontent/bump, mở/cập nhật PR, auto-merge (squash) nếu diff chỉ.md/.json, rồigh workflow run ci.yml --ref content/bumpđể có checkbuild(PR mở bằng GITHUB_TOKEN không kích hoạtpull_request). Merge ⇒ Workers Builds deploy.qodana.yml(từ v2.3.0, PR + pushmain+ tay): Qodana for JS (gói Ultimate, tokenQODANA_TOKEN), native mode trên Node 26 của runner saunpm ci+ sinh types, profileqodana.recommendedquét cả repo,failThreshold: 0(qodana.yamlghi các inspection tắt kèm lý do); kết quả lên Qodana Cloud và — vớimain— SARIF vào Code scanning. Bỏ qua PR Dependabot/fork (không có secret) nên chỉ là check tư vấn. Không phân tích.astro/.svelte.- Kiểm license:
gen-notices --check(dependency trực tiếp, bảng trongTHIRD-PARTY-NOTICES.md) +check-licenses(toàn bộ lockfile, ngoại lệ theo gói) trong jobbuild— chính sách ởscripts/license-policy.mjs(12_LEGAL/THIRD_PARTY_NOTICES.md). Qodana license audit cần Ultimate Plus nên không dùng. triage.yml(issues +pull_request_target; không checkout gì — đọcscripts/triage.mjscủa nhánh mặc định qua API rồi import từ bộ nhớ, nên không bao giờ chạy code của PR; Sonar S7631 bắt mọi checkout trongpull_request_target): đề xuất tính năng ⇒ nhãnenhancement+out-of-scope, bình luận song ngữ, đóng. Chạy khô bằngworkflow_dispatch.- Bẫy đã gặp: khi
maindính advisory, mọi PR (cả Dependabot) đỏ vì bước audit ⇒ vá gộp trong một PR rồi đóng các PR Dependabot bị thay thế.gen-notices --checktừng đếm số gói transitive ⇒ PR bump nào cũng đỏ; nay chỉ kiểm chính sách license.
1. Nguyên tắc
- Tái dùng hạ tầng
poli0981/.github: thêm reusable workflowweb-astro-ci.yml+web-astro-deploy.yml, repo này chỉ chứa caller stub — đúng mô hình 15 repo hiện tại. - Bài học Phase 5 áp lại: mọi caller stub khai
permissions:tường minh (caller thiếu ⇒ GitHub hạ tất cả vềnone). - Repo private ⇒ Actions tiêu phút miễn phí (Free plan: 2.000 phút/tháng). CI ước tính 3–4 phút/run → thoải mái, nhưng bật cache npm và không chạy CI cho thay đổi chỉ trong
docs/.
2. Pipeline
PR / push main
└── ci: install(npm ci, cache) → format:check → lint → astro check + tsc
→ knip → npm audit(high, omit dev) → build → check-exif(ảnh đổi)
push main (sau ci xanh)
└── deploy: build → pagefind → wrangler deploy (site) → wrangler deploy (widgets nếu đổi)
weekly (cron)
└── osv-scanner + npm outdated report → Discord webhook
3. Caller stub mẫu (.github/workflows/ci.yml)
name: CI
on:
pull_request:
push: { branches: [main] }
permissions: # tường minh — không để mặc định
contents: read
concurrency: { group: ci-${{ github.ref }}, cancel-in-progress: true }
jobs:
ci:
uses: poli0981/.github/.github/workflows/web-astro-ci.yml@main
with: { node-version: "24" }
Deploy stub thêm permissions: { contents: read } và
secrets: { CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID } (dùng cloudflare/wrangler-action bên trong reusable). Notify stub (nếu nối vào hệ notify hiện có): contents: read, actions: read — đúng matrix đã lập.
4. Secrets bootstrap
Mở rộng setup-secrets.sh hiện có:
gh secret set CLOUDFLARE_API_TOKEN -R poli0981/poli0981.dev
gh secret set CLOUDFLARE_ACCOUNT_ID -R poli0981/poli0981.dev
gh secret set DISCORD_WEBHOOK_CI -R poli0981/poli0981.dev # thông báo build
Secrets runtime của Worker (TURNSTILE_SECRET, GITHUB_ISSUES_TOKEN, DISCORD_WEBHOOK_BUG, STEAM_*) đặt bằng wrangler secret put — không đi qua GitHub.
5. Chất lượng code (chạy trong web-astro-ci)
| Bước | Lệnh | Cấu hình |
|---|---|---|
| Format | prettier --check . |
+ plugin astro, tailwindcss (thứ tự: tailwindcss cuối) |
| Lint | eslint . |
flat config: typescript-eslint strict + eslint-plugin-astro + eslint-plugin-svelte |
| Types | astro check && tsc --noEmit |
strict |
| Dead code | knip |
knip.json: entry astro.config.mjs, src/pages/**, src/content.config.ts, workers/widgets/src/index.ts; plugin Astro tự nhận |
| Audit | npm audit --omit=dev --audit-level=high |
fail = chặn merge |
| EXIF | node scripts/check-exif.mjs --changed |
fail nếu ảnh có GPS |
| Notices | node scripts/gen-notices.mjs --check |
THIRD-PARTY-NOTICES.md lệch ⇒ fail |
6. Dependabot (.github/dependabot.yml)
version: 2
updates:
- package-ecosystem: npm
directory: "/"
schedule: { interval: weekly, day: monday }
cooldown: { default-days: 3 } # không đề xuất bản phát hành < 3 ngày tuổi
open-pull-requests-limit: 8
groups:
astro: { patterns: ["astro", "@astrojs/*"] }
typescript: { patterns: ["typescript", "typescript-eslint"] }
dev-tools: { dependency-type: development }
ignore:
- dependency-name: typescript # giữ TS 6 cho tooling (02 §8)
update-types: ["version-update:semver-major"]
- dependency-name: prettier-plugin-astro # 1.x đổi khoảng trắng hiển thị — cần PR riêng
update-types: ["version-update:semver-major"]
- package-ecosystem: github-actions
directory: "/"
schedule: { interval: weekly }
workers/widgetskhông cópackage.json(không deps) nên không có mục riêng.@typescript/native(aliasnpm:typescript@7) không được Dependabot theo dõi — nâng tay (17§1).- Chính sách merge: patch/minor xanh CI → merge trong tuần; major → đọc upgrade guide, làm branch thử. Security alerts: xử lý ≤ 48h (lịch ở
17). PR bị một PR gộp thay thế ⇒ đóng kèm comment.
7. Git hooks (lefthook.yml)
pre-commit:
parallel: true
commands:
format: { glob: "*.{astro,svelte,ts,js,mjs,md,css,json,jsonc,yml,yaml}", run: npx prettier --write {staged_files}, stage_fixed: true }
lint: { glob: "*.{astro,svelte,ts,js,mjs}", run: npx eslint {staged_files} }
pre-push:
commands:
typecheck: { run: npm run check } # astro check
Commit và tag đều ký GPG; không dùng --no-verify.
8. Branch & release
mainprotected (ruleset): PR + check bắt buộc duy nhất làbuild(ruleset cho phép cả 3 kiểu merge; quy ước của repo là squash). Conventional Commits.- Mỗi PR: ngoài
buildcòn phải xanh (theo quy ước, ruleset không ép) SonarCloud quality gate, Qodana (ngưỡng 0) và CodeQL; Workers Builds trên nhánh PR chỉversions upload. - Chế độ bảo trì (D21): PR tính năng mới bị bot
triage.ymlđóng; mẫu PR có ô chọn 5 loại thay đổi được nhận (CONTRIBUTING.md). - Release: tag
vX.Y.Zcó ký GPG trên commitmainđã deploy + GitHub Release (notes lấy từCHANGELOG.md). Deploy vẫn là "mergemain" — tag chỉ đánh dấu mốc.v2.0.0= đợt nâng cấp 10/2026. Mỗi tag: sửasonar.projectVersiontrongsonar-project.propertiescho khớp. - Sau merge: kiểm
https://poli0981.dev/api/healthtrả đúng commit (07§9); nếu Workers Builds không deploy thì promote version củamainbằngwrangler versions deploy.