コンテンツにスキップ

0015. 品質ゲート (CI + 規律ベース運用 + 秘密スキャン)

コンテキストと課題

少人数開発で品質を保ちたいが、GitHub Free 組織の private リポジトリでは Branch Protection / Rulesets が使えないため、マージを機械的に強制できない。そこで「CI による自動チェック」と 「規律 (convention) ベースの運用」を組み合わせ、壊れたコードや秘密の混入を防ぐ仕組みが要る。

決定

1. CI 品質ゲート (自動・ci.yml)

.github/workflows/ci.yml が 全 PR と main/develop への push で次を実行する:

pnpm lint                         # Biome (lint + format チェック)
pnpm turbo run typecheck test build   # tsc --noEmit / vitest run / ビルド

Vite の env はビルド時 inline されるため、CI ではダミー値を渡してビルドが落ちないようにする。

2. テスト (Vitest)

  • フレームワークは Vitest。テスト環境は Web = happy-dom、API / shared / scripts = node。
  • 規律: 新規ロジックは「コード + テストをセット」で push し、追加ロジックには最低 1 件の正常系テストを書く (packages/shared/** の Zod/定数/純関数、apps/web/** の mapper/resolver 等)。

3. Lint / Format (Biome)

  • Biome に一本化 (ESLint / Prettier は不採用)。biome.json: 2 スペース・lineWidth 100・LF、 organizeImports、recommended ルール + noNonNullAssertion: warn + noExplicitAny: warn、 JS は single quote / JSX double / trailing all / semicolons always。

4. 規律ベース運用 (CONTRIBUTING.md)

  • Branch Protection が使えないため、ブランチ戦略・PR フロー・コミット規約・セルフレビューチェックリストを CONTRIBUTING.md で 規律として 定める (main 直 push 禁止、develop → main は PR 経由 等)。 GitHub Team 以上にアップグレードした際は同内容を Branch Protection / Ruleset として有効化する。

5. 秘密・SAST スキャン (レビュー時)

  • Gitleaks (シークレットスキャン) を使う。リポジトリには .gitleaksignore がコミットされており、 検証スクリプトに過去含まれた 公開 Supabase anon (publishable) key の履歴一致を allowlist している (公開鍵ゆえ無害)。秘密の非コミットは CONTRIBUTING の方針 (§7) とセルフレビュー (§8) でも担保する。
  • Semgrep (SAST、無料 OSS ルール) は コードレビュー時の運用 として用いる。実際に shell-injection ルールを満たす書き方をコード内コメントで明示している (initial-setup.yml の semgrep run-shell-injection 対策)。

影響 (Consequences)

良い点

  • Biome + tsc + Vitest + build を 1 つの CI で回し、ローカルでも pnpm lint && pnpm turbo run typecheck test build の同一コマンドで再現できる。lint/format を Biome に統一して設定の二重管理を避ける。
  • テスト環境をパッケージ特性に合わせて分離 (Web=happy-dom / それ以外=node) でき、過不足ない依存で速い。
  • 秘密混入は Gitleaks (+ .gitleaksignore による誤検知管理) とセルフレビューで多層に防ぐ。

トレードオフ / 注意点

  • Gitleaks / Semgrep は CI に組み込まれていない。CI (ci.yml) が回すのは Biome / typecheck / test / build のみで、CONTRIBUTING.md にも Gitleaks/Semgrep の記載はない。両者は レビュー時の 運用 であり、実行はレビュアーの規律に依存する (Gitleaks は .gitleaksignore の存在が痕跡、Semgrep は 専用設定ファイルを持たない)。CI への組込みは将来の改善余地。
  • 強制力が規律ベース。Branch Protection が無いため、品質ゲートは技術的にはバイパス可能で、運用の 徹底に依存する (Team 以上で Ruleset 化する前提)。
  • Web のコンポーネント描画テストは React インスタンス二重化のため vitest.config の alias 固定が必要、 という happy-dom 環境固有の注意点がある (ADR 0014)。

根拠 (典拠)

  • .github/workflows/ci.yml:9-13,49-61 — トリガー (main/develop の push + PR)、pnpm lint と pnpm turbo run typecheck test build。
  • CONTRIBUTING.md:3-7,75-93,95-112,160-169 — 規律ベース運用 (Branch Protection 不可)、Vitest 方針、ローカル品質確認コマンド、セルフレビューチェックリスト。
  • biome.json — formatter / linter (recommended + noNonNullAssertion/noExplicitAny warn) / JS スタイル。
  • apps/web/vitest.config.ts (environment: 'happy-dom') / apps/api/vitest.config.ts・packages/shared/vitest.config.ts (environment: 'node')。
  • .gitleaksignore — 公開 Supabase anon key の履歴一致を allowlist (Gitleaks 利用の痕跡)。
  • .github/workflows/initial-setup.yml:60 — semgrep run-shell-injection 対策 のコメント (Semgrep ルールを満たす書き方)。
  • README.md:13,125-128 — Biome 採用、規律ベース運用の注記。