Files
poli0981andClaude Opus 5.5 7bcbcf59dd docs: maintenance mode — policy, triage bot, issue forms, status badge, docs for 2.3.0 (#139)
* 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>
2026-11-21 08:48:09 +07:00

10 KiB
Raw Permalink Blame History

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, push main, workflow_dispatch), job build (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) → typecheck bằng TypeScript 7 (in tsc -v, kiểm site + widgets) → knip → test:coverage (node:test, ngưỡng 80% dòng, xuất coverage/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ằng wrangler 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 preview chạy nền rồi npm 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. Check build là bắt buộc (ruleset main), nên PR có vi phạm axe không merge được.
  • Job sonarcloud (sau build; chạy cho push main và PR cùng repo, bỏ qua Dependabot): tải coverage → SonarSource/sonarqube-scan-action (pin SHA) với sonar-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_TOKEN là secret của repo. .svelte/.astro khô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-action pin 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; concurrency gộp các lần gọi dồn dập): trỏ submodule src/content về content/main, commit lên nhánh content/bump, mở/cập nhật PR, auto-merge (squash) nếu diff chỉ .md/.json, rồi gh workflow run ci.yml --ref content/bump để có check build (PR mở bằng GITHUB_TOKEN không kích hoạt pull_request). Merge ⇒ Workers Builds deploy.
  • qodana.yml (từ v2.3.0, PR + push main + tay): Qodana for JS (gói Ultimate, token QODANA_TOKEN), native mode trên Node 26 của runner sau npm ci + sinh types, profile qodana.recommended quét cả repo, failThreshold: 0 (qodana.yaml ghi các inspection tắt kèm lý do); kết quả lên Qodana Cloud và — với main — 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 trong THIRD-PARTY-NOTICES.md) + check-licenses (toàn bộ lockfile, ngoại lệ theo gói) trong job build — 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ì — đọc scripts/triage.mjs củ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 trong pull_request_target): đề xuất tính năng ⇒ nhãn enhancement + out-of-scope, bình luận song ngữ, đóng. Chạy khô bằng workflow_dispatch.
  • Bẫy đã gặp: khi main dí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 --check từ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 workflow web-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/widgets không có package.json (không deps) nên không có mục riêng.
  • @typescript/native (alias npm: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

  • main protected (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 build cò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.Z có ký GPG trên commit main đã deploy + GitHub Release (notes lấy từ CHANGELOG.md). Deploy vẫn là "merge main" — tag chỉ đánh dấu mốc. v2.0.0 = đợt nâng cấp 10/2026. Mỗi tag: sửa sonar.projectVersion trong sonar-project.properties cho khớp.
  • Sau merge: kiểm https://poli0981.dev/api/health trả đúng commit (07 §9); nếu Workers Builds không deploy thì promote version của main bằng wrangler versions deploy.