CI 運用方針（品質ゲート）

本ドキュメントは 意図した CI 設計 の正本です。Actions 課金上限への対応として採用しています。

AI エージェント・Copilot レビュー: コードレビューや PR コメントで CI を提案するときは、必ず本ページの「推奨しない変更」を守ること。

背景

• 旧運用: 品質ワークフロー 6 本 × pull_request（毎 push）× develop push → 分数消費が大きい
• 制約: 個人の無料アカウント + プライベートリポ のため Merge Queue は利用不可
• 現行: Plan B（統合 1 ワークフロー + 限定的トリガー）

現行の設計（意図）

項目	方針
ワークフロー	ci-quality-gate.yml 1 本（複数チェックを 1 ジョブで順次実行）
GitHub Actions トリガー	pull_request（opened / reopened / ready_for_review）、develop への push、workflow_dispatch
追加 push（synchronize）	CI を自動起動しない（意図的）
develop への merge 後 push	1 回走る（マージ後検証。docs/**・*.md のみの変更は除外）
マージ前の検証	workflow_dispatch（Run workflow）で PR head を検証
開発中の品質確認	ローカルで個別またはまとめて実行

develop push 時の実行（Issue #3853）

• PR を develop にマージしたときに Quality Gate を 1 回 実行し、マージ後の develop 先端を検証する。
• 必須チェック化・synchronize の追加・デプロイゲートは行わない（Actions 分数の制約のため見送り）。
• develop が赤くなった場合は、その run か次の PR の初回 run で検知し、修正 PR を出して直す。
• docs/** と *.md のみのマージでは起動しない。docs/ 配下のファイル（custom-tables.dbml と DBML サブセット、VitePress のスクリプト・CSS など）や Markdown に対する Prettier・ESLint・CSS lint・DBML サブセット検査はマージ後に検証されないため、docs のみの PR でもマージ前に Run workflow かローカルの composer quality-check:full で確認する。
• 連続してマージした場合は concurrency により古い run が取り消され、最新の先端だけが検証される。

推奨しない変更（レビューで提案しないこと）

以下は リグレッション または 課金再燃 になりうるため、本ポリシーの意図に反します。

1. pull_request に synchronize を戻す、または types 未指定で全 PR イベントにする
   → 毎 push で CI が走り、旧運用と同様に分数が増える

2. develop push 時の Quality Gate を必須チェック化する、またはデプロイゲートにする
   → develop push トリガーはマージ後検証として採用済み（Issue #3853）。必須化・デプロイゲート化は分数と運用負荷の観点で見送っている

3. 6 本の個別ワークフローに再分割する（各々が composer install する）
   → 1 回の検証あたりの分数が増える

4. Merge Queue / merge_group のみを前提にした手順を、現プランでは唯一の解として勧める
   → 個人無料プライベートでは設定できない

5. 「CI が付いていないから push ごとにチェックを足すべき」という指摘を、設計ミスとして扱う
   → 追加 push で Checks が付かないのは 仕様。対処は Run workflow とローカルチェック

6. 追加 push 後の検証に「Re-run all jobs」だけを勧める
   → Re-run は 元の workflow run と同じコミット SHA を再実行するだけ。最新 head を検証するには Actions → CI Quality Gate → Run workflow（pr_number 入力または PR ブランチ選択）を使う

推奨するレビュー・開発の言い方

状況	推奨
PR に push した直後	ローカルで composer quality-check と、触った領域の個別コマンド（例: composer test / npm run typecheck）
マージ前（ローカル）	composer quality-check:full（CI Quality Gate 相当の一括）または個別コマンドの組み合わせ
マージ前（Actions）	Actions → CI Quality Gate → Run workflow（pr_number または PR ブランチ）
CI 失敗の修正後	修正を push → Run workflow（自動では再実行されない）
develop の run が赤	失敗内容を確認し、修正 PR を出す（マージで再度 develop push の run が走る）
ワークフロー変更の PR	マージ後に Ruleset の必須チェック名が CI Quality Gate / Quality Gate か確認

ローカルコマンド（個別実行は引き続き可）

チェック	コマンド
PHPCS	composer lint
PHPCS（tests）	composer lint-tests
PHPStan（core_src + tests）+ Deptrac	composer ci-static-check
PHPUnit	composer test
PSR-4	composer psr4
Format	npm run format:check
Format（Twig）	npm run format:twig:check
JavaScript lint	npm run lint:js
CSS lint	npm run lint:css
TypeScript typecheck	npm run typecheck
Vitest 等	npm run test
Webpack build	npm run build
jscpd（レポート）	npm run duplicates
jscpd（閾値超過で fail）	npm run duplicates:check
Shell Lint（shellcheck）	composer shellcheck または ./bin/run_shellcheck.sh
Composer audit（root）	composer audit（ネイティブコマンド）
Composer audit（core_src）	composer audit -d core_src または composer audit:core
Composer audit（両方）	composer audit:all
npm audit（本番依存・high 以上で fail）	npm run audit
npm audit（dev 含む）	npm run audit:all（現状 fail しうる。CI 対象外）
依存 audit 一括（CI と同内容）	composer dependency-audit または ./bin/run_dependency_audit.sh
PHP 静的まとめ（PHPCS + PHPStan + Deptrac）	composer quality-check または ./bin/run_local_quality_check.sh
CI Quality Gate 相当の一括	composer quality-check:full または ./bin/run_ci_quality_gate_local.sh

composer quality-check は PHP 静的解析のみであり、PHPUnit / Prettier / ESLint / Vitest / build / jscpd は含まない。CI ゲート全体をローカルで再現するときは composer quality-check:full を使う（npm run lint:css を含む）。

COMPOSER_NO_AUDIT=1 について

CI（ci-quality-gate.yml）とローカル共通スクリプト（scripts/common.sh）、および bin/run_ci_quality_gate_local.sh では、composer install 時の自動 audit を COMPOSER_NO_AUDIT=1 で無効にしている。install のノイズ・時間を抑え、品質チェック本体と分離するためである。代替として Quality Gate 内および composer dependency-audit / ./bin/run_dependency_audit.sh で明示的に composer audit（root + core_src）を実行する。npm は本番依存のみ npm run audit（npm audit --omit=dev --audit-level=high）をゲート対象とする（dev 含む監査はローカルの npm run audit:all）。Composer は severity フィルタなし（low 含む全 advisory で fail）、npm は high 以上のみ fail。

Packagist の security-advisories API が一時的に 502 等になる場合があるため、run_dependency_audit.sh は Composer audit を短時間 retry する。--ignore-unreachable はローカルの一時確認用であり、CI では使わない。

変更を検討する場合

CI トリガーを変える PR を出すときは、次を PR 説明に書くこと:

• 想定する Actions 分数への影響
• Merge Queue が使えない前提での代替

関連

• CI 概要
• CI Quality Gate
• develop ブランチの保護
• ワークフロー定義: .github/workflows/ci-quality-gate.yml