cicd-playbook

CI/CD プレイブックのスキル

サービスやチーム向けに、実行可能な CI/CD プレイブックを完全な形で作成します。新しいエンジニアがパイプラインを理解し、安全に貢献・運用するために必要な情報をすべて網羅します。

優れたプレイブックは図ではありません。「何が、いつ、なぜ実行され、誰が所有し、問題が発生したときに何をすべきか」に答えるドキュメントです。

必要な入力情報

まだ提供されていない場合は、以下を確認してください。

• サービス名と簡単な説明
• 技術スタック — 言語、フレームワーク、コンテナ化（Docker など）
• ソース管理 — GitHub／GitLab／Bitbucket、ブランチ戦略
• CI プラットフォーム — GitHub Actions／CircleCI／Jenkins／BuildKite／その他
• CD プラットフォーム／デプロイ先 — Kubernetes、ECS、Lambda、Heroku、VM など
• 環境 — 例：dev、staging、production（および canary／feature 環境）
• デプロイ頻度 — チームはどのくらいの頻度でリリースしますか？
• 既存のゲート — 手動承認、スモークテスト、フィーチャーフラグ
• オンコール体制 — デプロイ中の担当者は誰ですか？

出力形式

---

CI/CD プレイブック：[Service Name]

サービス： [Name] | チーム： [Team name] 最終更新日： [Date] | 担当者： [Name / role] パイプラインプラットフォーム： [CI tool] → [CD tool / platform]

---

概要

[このサービスの機能と、CI/CD パイプラインがそのように構成されている理由を説明する文章を2〜3文で記述します。デプロイ先と、チームのリリース頻度も含めてください。]

デプロイ頻度： [1日に複数回／毎日／毎週／オンデマンド] パイプラインの平均所要時間： [X 分] ロールバック時間（p95）： [X 分]

---

パイプラインのステージ

[Branch push]
    │
    ▼
[1. Build & Lint] ──fail──▶ ❌ Block PR
    │
    ▼
[2. Unit Tests] ──fail──▶ ❌ Block PR
    │
    ▼
[3. Integration Tests] ──fail──▶ ❌ Block PR
    │
    ▼
[4. Security Scan] ──fail──▶ ⚠️ [Block / Warn — specify]
    │
    ▼
[5. Build Artefact / Container Image]
    │
    ▼
[6. Deploy to Staging] ──fail──▶ ❌ Block promotion
    │
    ▼
[7. Smoke Tests (Staging)]
    │
    ▼
[8. Manual Approval Gate] ──(if required)
    │
    ▼
[9. Deploy to Production] ──fail──▶ 🔁 Auto-rollback (if configured)
    │
    ▼
[10. Post-deploy checks]

---

ステージの定義

ステージ 1 — ビルドとリント

実行内容： [ビルドコマンド] + [リンター — 例：ESLint、golangci-lint、flake8] トリガー： すべてのブランチへのコミット ブロッキング： はい — 失敗すると PR をマージできません 通常の所要時間： [X 分] 失敗時の担当者： PR の作成者

よくある失敗原因：

• [例：依存関係が不足している — プッシュ前にローカルで npm install を実行してください]
• [例：Lint ルール違反 — npm run lint --fix を実行すると、多くの問題を自動修正できます]

---

ステージ 2 — ユニットテスト

実行内容： [テストコマンド — 例：npm test、go test ./...、pytest] カバレッジゲート： 最低 [X]% — このしきい値を下回るとパイプラインは失敗します トリガー： すべてのコミット ブロッキング： はい 通常の所要時間： [X 分]

カバレッジレポート： [確認場所 — 例：Codecov にアップロード、CI アーティファクトから参照可能]

---

ステージ 3 — 統合テスト

実行内容： [テストスイートの説明 — 例：「Docker Compose を使用し、テスト用データベースに対して API 統合テストを実行」] 環境： [一時的なテスト環境／共有テスト DB など] トリガー： main および main を対象とする feature ブランチへのすべてのコミット ブロッキング： はい 通常の所要時間： [X 分]

時間がかかる場合： [例：「統合テストはローカルでは SKIP_INTEGRATION=true を指定してスキップできます — CI では絶対にスキップしないでください」]

---

ステージ 4 — セキュリティスキャン

ツール： [例：Snyk、Trivy、OWASP Dependency Check、Semgrep] チェック対象： [依存関係の脆弱性／SAST／シークレット検出 — 該当するものを列挙] ブロッキング対象： Critical および High の重大度の検出結果 ブロッキング対象外： Medium および Low（フラグは付けられますが、ブロックはしません） トリガー： main へのすべてのコミット

脆弱性が検出された場合の対処方法：

1. 修正が利用可能か確認します — 依存関係をアップグレードします
2. 修正が利用できない場合は、セキュリティチケットを起票し、正当な理由を添えて抑制を追加します
3. チケットと担当者を設定せずに抑制してはいけません

---

ステージ 5 — ビルド成果物

生成物： [Docker イメージ／バイナリ／zip — 具体的に記載] レジストリ： [ECR／GCR／Docker Hub／Artifactory — URL] タグ付け規則： [service-name]:[git-sha]（main では :latest タグも付与） トリガー： main へのコミットのみ（feature ブランチは対象外）

---

ステージ 6 — ステージング環境へのデプロイ

デプロイ方法：［例：Helm upgrade／kubectl apply／ecs deploy／Terraform apply］ ステージング URL：［URL］ トリガー： main からのアーティファクトビルドが成功すると自動実行 **ステージング環境にデプロイできる人：**すべてのエンジニア（自動）

環境変数：［Vault／AWS SSM／GitHub Secrets など］で管理 ステージング環境は本番環境ではありません：［設定、規模、データの違いがあれば、ここに記載してください］

---

ステージ 7 — スモークテスト（ステージング環境）

実行内容：［説明 — 例：「ログイン、主要な API エンドポイント、決済フローを網羅する重要なパスのテスト 10 件」］ ツール：［例：Playwright／Postman／カスタムスクリプト］ **合格条件：**すべてのスモークテストが［X 秒］のタイムアウト以内に合格すること **ブロック条件：**あり — スモークテストが失敗した場合、本番環境へのデプロイは実行されません

スモークテストスイートの場所：［テストファイルまたはフォルダーへのリンク］

---

ステージ 8 — 手動承認ゲート

適用対象：［本番環境へのデプロイ／トラフィックの［X］% を超える範囲に影響するデプロイ／特定のリージョンへのデプロイ］ 承認できる人：［例：チーム内のすべてのエンジニア／リードエンジニア／オンコールエンジニア］ 承認タイムアウト：［例：24 時間 — 承認がなければ自動キャンセル］ 承認方法：［GitHub Actions の承認ステップ／Slack コマンド／その他 — リンクを含めてください］

承認を保留する場合：

• 本番環境でインシデントが発生中
• デプロイ時間枠外のデプロイ（以下を参照）
• オンコールエンジニアに通知されていない

---

ステージ 9 — 本番環境へのデプロイ

デプロイ方法：［ステージング環境と同じ、または異なる場合は指定］ デプロイ時間枠：［例：月曜日～木曜日 09:00～16:00 UTC — 金曜日および祝日の前日はデプロイしません］ カナリア／段階的ロールアウト：［はい — 初期トラフィックの X% に適用し、Y 分後に全体へ展開／いいえ — 全体にデプロイ］ デプロイ通知：［Slack チャンネル — #deployments］

**デプロイ中のオンコール担当者：**デプロイ担当エンジニアは、デプロイ後のチェックに合格するまで責任を負います。

---

ステージ 10 — デプロイ後のチェック

自動チェック（デプロイ後［X 分間］実行）：

• エラー率：＜［X］%（ベースライン：［Y］%）
• P99 レイテンシ：＜［X］ms（ベースライン：［Y］ms）
• ［主要なビジネス指標］：ベースラインの［X］% 以内

確認場所：［Datadog／Grafana／CloudWatch ダッシュボード — リンク］

**チェックに失敗した場合：**以下のロールバック手順を参照してください。

---

環境

環境	目的	デプロイのトリガー	URL	データ
開発	ローカル開発	手動	localhost	テスト用にシードされたデータ
ステージング	本番前の検証	自動（main）	［URL］	匿名化された本番環境のコピー
本番	ライブトラフィック	手動承認	［URL］	ライブデータ

---

ブランチ戦略

モデル：［トランクベース／GitFlow／GitHub Flow — 簡単に説明してください］

ブランチ	目的	マージする人	デプロイ先
main	本番環境に適したコード	PR + レビュー	ステージング → 本番
feature/*	機能開発	作成者	なし（CI のみ）
hotfix/*	本番環境の重大な修正	リードエンジニア	承認があればステージングゲートを省略可能

ホットフィックスのプロセス：［ホットフィックスブランチを使用するタイミングと方法、および標準プロセスの省略が妥当となるインシデントの重大度を説明してください］

---

ロールバック手順

自動ロールバック：［あり — デプロイ後にエラー率が［X］% を超えた場合に実行／なし — 手動のみ］

手動ロールバックの手順：

# 1. Identify the last known good image tag
[command to list recent deployments]

# 2. Deploy the previous version
[deployment command with previous tag]

# 3. Confirm rollback is live
[smoke test command or health check URL]

# 4. Notify the team
[Slack command or template]

**ロールバックの決定権限：**オンコール中のエンジニアは、承認を待たずにロールバックを開始できます。

ロールバック後：

1. デプロイ後のインシデントレポートを作成します（［incident-postmortem skill］を参照）
2. 根本原因を修正せずに同じコミットを再デプロイしないでください
3. ロールバックと修正の予定時期を［関係者／サポートチーム］に通知します

---

シークレットと構成の管理

シークレットストア： [Vault / AWS SSM / GitHub Secrets / Doppler — 指定してください] 新しいシークレットの追加方法：

1. [手順 1]
2. [手順 2] アクセスできるユーザー： [役割またはチーム] ローテーションポリシー： [シークレットをローテーションする頻度と担当者]

禁止事項： .env ファイル内であっても、シークレットをソース管理にコミットしないでください。パイプラインにはシークレットスキャン（ステージ 4）が含まれており、違反は検出されます。

---

よくある失敗と対処法

失敗	考えられる原因	対処法
「module not found」でビルドが失敗する	依存関係がインストールされていない	[install command] を実行し、lock file をコミットします
統合テストがタイムアウトする	テスト用データベースがシードされていない／外部サービスが停止している	[service] のステータスを確認し、パイプラインを再実行します
ステージングへのデプロイ後にスモークテストが失敗する	環境変数が不足している	[config location] を確認し、ステージングと本番環境の環境変数を比較します
承認待ちで本番デプロイが停止する	承認者に通知されていない	#deployments で @[on-call handle] にメンションします
デプロイ後にエラー率が急上昇する	不適切なデプロイ／上流の依存関係	[dashboard] を確認し、5 分を超える場合はロールバックを開始します

---

デプロイ中のオンコール担当者の責任

• 本番環境へのデプロイ後、デプロイ担当エンジニアは [X minutes] の間、デプロイ後のチェックを監視する責任があります
• デプロイ後に監視できない場合は、#deployments で別のエンジニアに明示的に引き継いでください
• 営業時間外のデプロイはホットフィックスに限ります。デプロイ前に必ずオンコールエンジニアにページャーで通知してください

---

アンチパターン

• 一度もテストしていないロールバック手順を記述しないでください。理論上のロールバックはロールバック計画ではありません。本番環境へのデプロイ前に、ステージング環境でテストしてください
• 週末を通じて監視するオンコールエンジニアが明確に決まっていない限り、金曜日や祝日の前にデプロイできるようにしないでください
• 本番環境以外のブランチであっても、シークレットをソース管理にコミットしないでください。パイプラインのシークレットスキャンで検出されますが、未然に防ぐことが基本です
• 本番環境へのデプロイ後の監視を省略しないでください。デプロイ担当エンジニアは、指定された監視期間中、エラー率とレイテンシーを確認する必要があります
• セキュリティスキャンで検出された問題を、関連チケットと担当者を明記せずに抑制しないでください。説明責任のない抑制は蓄積し、管理されていないリスクにつながります

品質チェック

• 各ステージで失敗した場合の担当者が明確になっている
• ロールバック手順が理論上のものではなく、テスト済みである
• シークレット管理のセクションで、実際に使用するツールを明記している（「シークレット管理を使用する」ではない）
• デプロイ時間帯が具体的に指定されている（「営業時間内」ではない）
• デプロイ後のチェックのしきい値が、実際のベースライン指標に合わせて調整されている

想定されるトリガーフレーズ

• 「CI/CD パイプラインを文書化してください。」
• 「デプロイプロセスを作成してください。」
• 「リリースゲートを定義してください。」
• 「ビルドとテストの各ステージを文書化してください。」
• 「デプロイガイドを作成してください。」