infra-ci-cd-github-actions

CI/CD パイプライン

クイックガイド： CI/CD には GitHub Actions を使用します。モノレポの最適化には、影響範囲の検出（例：Turborepo の --affected または --filter=...[origin/main]）を行います。高速な CI のために、依存関係とビルド出力をキャッシュします。品質ゲートとして、lint + 型チェック + テスト + ビルド + カバレッジを必須のステータスチェックに設定します。ビルドのプロモーションを用いて、複数環境へデプロイします。クラウドプロバイダーの認証には OIDC を使用します。すべてのアクションとランタイムのバージョンを固定してください。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

（PR ビルドでは、影響を受けるパッケージ／変更されたパッケージを必ず検出してください。PR でテストスイート全体を実行してはいけません）

（パッケージマネージャーの依存関係とビルド出力を必ずキャッシュしてください。キャッシュのない CI では実行時間の 70% が無駄になります）

（アクションのバージョンは必ず固定してください（actions/checkout@v6、oven-sh/setup-bun@v2、actions/cache@v5）。@main やバージョン指定のないアクションは使用してはいけません）

（品質ゲート（lint + 型チェック + テスト + ビルド）を必須のステータスチェックとして必ず設定してください。失敗した場合はマージをブロックしてください）

（対応しているクラウドプロバイダーでは、認証に必ず OIDC を使用してください。長期間有効な静的認証情報は使用してはいけません）

</critical_requirements>

---

詳細なリソース：

• examples/core.md - パイプライン設定、ジョブ、キャッシュ、再利用可能なワークフロー、複合アクション、マトリックスビルド
• examples/testing.md - 影響範囲の検出、品質ゲート
• examples/caching.md - リモートキャッシュ、Turborepo
• examples/security.md - OIDC 認証、シークレットのローテーション、アーティファクトの証明
• examples/deployment.md - 複数環境、ロールバック
• examples/monitoring.md - CI メトリクス、GitHub Insights
• reference.md - 判断フレームワーク、アンチパターン、定数リファレンス

---

自動検出： GitHub Actions、CI/CD パイプライン、.github/workflows、Turborepo の影響範囲の検出、リモートキャッシュ、デプロイの自動化、品質ゲート、OIDC 認証、シークレットのローテーション、アーティファクトの証明、SLSA の来歴情報、再利用可能なワークフロー、複合アクション、マトリックスビルド、workflow_call

使用する場面：

• モノレポ向けに GitHub Actions のワークフローを設定する
• PR ビルドを高速化するために影響範囲の検出を導入する
• ビルド成果物を共有するためにリモートキャッシュを設定する
• 品質ゲートとブランチ保護ルールを設定する
• クラウドへのデプロイに OIDC 認証を導入する
• サプライチェーンのセキュリティ向上のためにアーティファクトの証明を追加する

使用しない場面：

• GitHub を使用していないプロジェクト（使用する CI プロバイダーの公式ドキュメントを参照してください）
• 自動テストやビルドのステップが不要な場合

対象となる主要なパターン：

• 並列ジョブと依存関係のキャッシュを用いたパイプライン設定
• 影響範囲の検出（Turborepo の --affected フラグまたは --filter=...[origin/main]）
• 品質ゲート（依存関係を設定した並列ジョブとしての lint、型チェック、テスト、ビルド）
• OIDC 認証（クラウドプロバイダーに静的認証情報を使用しない）
• 再利用可能なワークフロー（workflow_call、合計で最大 10 階層）
• 複合アクション（using: composite、セットアップロジックの共有）
• マトリックスビルド（include/exclude、fail-fast、動的マトリックス）
• アーティファクトの証明（SLSA v1.0 Build Level 2 の来歴情報）
• ビルドのプロモーションを用いた複数環境へのデプロイ

---

基本方針

CI/CD パイプラインは、テスト、ビルド、デプロイを自動化します。モノレポでは、コードベースの拡大に伴って CI の高速性を維持するために、インテリジェントなキャッシュと影響範囲の検出が欠かせません。

基本原則：

• 迅速なフィードバック： 影響範囲の検出とキャッシュを活用し、PR ビルドを 5 分未満で完了させます
• 一度ビルドして、あらゆる環境にプロモーション： 1 つのビルド成果物をプレビュー／ステージング／本番環境にデプロイします
• 静的認証情報を使わない： クラウドプロバイダーには OIDC を使用し、ローテーションする認証情報にはシークレットマネージャーを使用します
• 品質ゲートでマージをブロック： マージ前に lint、型チェック、テスト、ビルドのすべてに合格する必要があります

---

## 基本パターン

パターン 1：パイプラインの設定

インストールと並列での品質チェックを分け、その後にビルドします。

# Recommended workflow structure:
# ci.yml      - lint, test, type-check, build (PR + main)
# deploy.yml  - production deployment from main
# preview.yml - preview deployments for PRs

主な決定事項：

• ランタイムとアクションのバージョンを固定します（latest は使用しないでください）
• 依存関係をキャッシュするインストールジョブを分け、その後、lint／テスト／型チェックを並列に実行します
• すべての品質ゲートに合格してからビルドします
• concurrency と cancel-in-progress: true を使用して、リソースの無駄を防ぎます

完全なワークフローの例は、examples/core.md を参照してください。

---

パターン 2：変更箇所の検出

モノレポでは、変更されたパッケージのみをテストおよびビルドします。

Turborepo の例（2 つの方法のいずれかを選択）：

# Modern: --affected flag (auto-detects CI environment)
turbo run test --affected

# Manual: --filter with git comparison
turbo run test --filter=...[origin/main]

主な原則： PR では変更箇所の検出を使って、迅速にフィードバックを得ます（5 分未満）。メインブランチでは、全スイートを実行します。

注意点： 新しいパッケージには Git の履歴がないため、変更箇所の検出でスキップされます。新しい package.json ファイルがないか必ず確認し、見つかった場合は全スイートにフォールバックしてください。

PR とメインブランチのワークフローの例は、examples/testing.md を参照してください。

---

パターン 3：品質ゲート

マージ前に合格が必須となる自動チェックです。

品質ゲートの順序：

1. Lint（コードスタイルと静的解析）
2. 型チェック（TypeScript のエラー）
3. カバレッジ付きテスト（機能の検証）
4. ビルドの検証（本番用ビルドが成功すること）
5. バンドルサイズのチェック（パフォーマンスの低下を防止）
6. セキュリティ監査（依存関係の脆弱性）

ブランチ保護で必須のステータスチェックとして設定します。マージ前にブランチが最新であることを必須にするには、strict: true を使用します。

包括的な品質ゲートのワークフローについては、examples/testing.md を参照してください。

---

パターン 4：OIDC 認証

クラウドへのデプロイで、静的な認証情報を排除します。

# Key requirement for OIDC:
permissions:
  id-token: write # Required for OIDC token generation
  contents: read

OIDC によって不要になるもの： 手動でのキーのローテーション、キー漏えいによる恒久的なセキュリティリスク、追跡できないデプロイです。一時的な認証情報は自動的に有効期限が切れます（通常は 1 時間）。

AWS OIDC とトークンベースの認証の例は、examples/security.md を参照してください。

---

パターン 5：再利用可能なワークフローと複合アクション

リポジトリ間で CI/CD ロジックを一元管理します。

機能	再利用可能なワークフロー	複合アクション
適用範囲	複数のジョブ	ジョブ内のステップ
シークレット	secrets コンテキストをネイティブに使用	入力を介して渡す必要がある
ネスト	合計 10 レベルまで（呼び出し元 + ネスト 9 層）、実行ごとに一意のものを 50 個まで	該当なし
用途	パイプライン全体のテンプレート	共有セットアップ／ティアダウン

実装例は、examples/core.md を参照してください。

---

パフォーマンスの最適化

目標：PR ビルドの CI 実行時間を 5 分未満にする

並列化の手法：

• インストールジョブを分け、lint／テスト／型チェックのジョブを並列に実行します（時間を 40% 短縮）
• 複数の OS／バージョンに対応するマトリックスビルドを使用します（PR ではなくメインブランチでのみ実行）
• テストスイートを分割し、単体テスト、統合テスト、E2E テストを並列ジョブとして実行します
• concurrency と cancel-in-progress: true を使用して、古い実行をキャンセルします

監視目標：

• CI 実行時間： 5 分未満（PR）、10 分未満（メインブランチ）
• キャッシュヒット率： 80% 超（リモートキャッシュ）
• 失敗率： 5% 未満（不安定なテストを除く）
• デプロイまでの時間： 10 分未満（コミットから本番環境まで）

---

<red_flags>

注意すべき重大な問題

優先度：高

• すべての PR でテストスイート全体を実行する - 影響範囲の検出を使用してください。そうしないと、CI に 10 分以上かかります
• キャッシュが設定されていない - 毎回依存関係を再インストールすると、2～3 分の無駄になります
• ランタイムバージョンに latest を使用する - ビルドの非決定性により、再現性が損なわれます
• 静的なクラウド認証情報をシークレットに保存する - OIDC 認証を使用し、長期間有効なアクセスキーは決して保存しないでください
• シークレットをリポジトリにコミットする - GitHub Secrets を使用し、YAML に認証情報をハードコードしないでください
• main ブランチに品質ゲートがない - lint／テスト／型チェックがないと、壊れたコードがマージされる可能性があります

優先度：中

• ジョブを並列ではなく順次実行する - インストール後、lint／テスト／型チェックは並列に実行してください
• concurrency の上限がない - 同じ PR で複数の CI 実行が発生し、リソースが無駄になります
• 環境ごとに再ビルドする - 一度ビルドし、アーティファクトを各環境に昇格させてください
• CI のパフォーマンスを監視していない - 実行時間とキャッシュヒット率を追跡しないと、ボトルネックを特定できません
• ワークフローにマジックナンバーがある - 意図の説明がないタイムアウトやしきい値がハードコードされています

よくある間違い：

• 影響範囲の検出で fetch-depth: 0 を使用しない（履歴がないと git diff が失敗します）
• すべてのジョブで needs: [all, previous, jobs] を使用する（順次実行になります）
• 影響範囲の検出で新しいパッケージを処理しない（スキップされます）

注意点とエッジケース：

• 影響範囲の検出には fetch-depth: 0 が必要です（浅いクローンでは git diff が機能しません）
• 新しいパッケージには git 履歴がないため、影響範囲の検出でスキップされます
• actions/cache のデフォルト上限はリポジトリあたり 10GB です（最大 10TB まで設定可能で、追加ストレージは $0.07/GiB/月で課金されます）
• OIDC には id-token: write 権限が必要です。ない場合、トークンの生成はエラーを通知せずに失敗します
• 環境シークレットは、同じ名前のリポジトリシークレットより優先されます
• アーティファクト証明には attestations: write、id-token: write、および contents: read が必要です
• 再利用可能なワークフローは合計 10 階層（呼び出し元＋ネスト 9 階層。以前の 4 階層から増加）まで、1 回の実行につき一意なものを 50 個までサポートします
• actions/create-release は非推奨です。代わりに softprops/action-gh-release@v2 を使用してください
• workflow_dispatch は現在、25 個の入力をサポートしています（10 個から増加）

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md に記載されたプロジェクトの規約に従う必要があります

（PR ビルドでは、必ず影響範囲／変更されたパッケージの検出を使用してください。PR でテストスイート全体を実行してはいけません）

（パッケージマネージャーの依存関係とビルド出力は必ずキャッシュしてください。キャッシュなしの CI では、実行時間の 70％が無駄になります）

（アクションのバージョンは必ず固定してください（actions/checkout@v6、oven-sh/setup-bun@v2、actions/cache@v5）。@main やバージョン指定なしは使用しないでください）

（品質ゲート（lint＋型チェック＋テスト＋ビルド）を必須のステータスチェックとして必ず実装し、失敗時はマージをブロックしてください）

（対応している場合は、クラウドプロバイダーの認証に必ず OIDC を使用してください。長期間有効な静的認証情報は使用しないでください）

これらのルールに従わないと、CI の遅延（10 分以上）、セキュリティ上の脆弱性（認証情報の漏えい）、ビルドの破損（品質ゲートの欠落）が発生します。

</critical_reminders>