パイプライン実行の失敗
ソース取得の失敗
症状:
- GitHubやCodeCommitからのソースコード取得が失敗する
原因と対処:
- 【認証エラー】
CodePipelineのサービスロールにソースリポジトリへのアクセス権限がない → IAMポリシーを確認・修正
- 【ブランチ不一致】
指定したブランチが存在しない → パイプライン設定でブランチ名を確認
- 【接続エラー】
GitHub接続の期限切れ → CodePipelineのコンソールで接続を再認証
- 【Webhook未設定】
自動トリガーが動作しない → リポジトリのWebhook設定を確認
ビルドの失敗
症状
原因と対処
- 【buildspec.ymlの構文エラー】
YAMLのインデントやコマンドミス → buildspec.ymlを検証し、ローカルでも動作確認
- 【環境変数の不足】
必要な環境変数が設定されていない → CodeBuildプロジェクトの環境変数を確認
- 【依存関係のインストール失敗】
パッケージマネージャーのエラー → ビルドログで具体的なエラーを確認、バージョン指定を見直し
- 【タイムアウト】
ビルド時間が制限を超過 → CodeBuildのタイムアウト設定を延長、ビルドプロセスを最適化
- 【権限不足】
ECRへのpush権限やS3へのアクセス権限がない → CodeBuildのサービスロールを確認
デプロイの失敗
症状
原因と対処
- 【デプロイ先リソースの不在】
EC2インスタンス、ECSサービス、Lambda関数が存在しない → デプロイ先を事前に作成
- 【権限エラー】
デプロイアクションに必要な権限がない → サービスロールのIAMポリシーを確認
- 【CloudFormationスタックエラー】
テンプレートの構文エラーやリソース制限 →CloudFormationのイベントログを確認
- 【ヘルスチェック失敗】
デプロイ後のアプリケーションが正常起動しない → アプリケーションログとヘルスチェック設定を確認
権限とロールの問題
サービスロールの権限不足
症状
対処方法
- CodePipelineサービスロールに必要な権限を付与
S3へのアクセス権限（アーティファクト保存）
CodeBuildプロジェクトの実行権限
デプロイ先サービス（ECS、Lambda、EC2など）への権限
CloudFormationの実行権限
- 最小権限の原則を守りつつ、必要な権限を段階的に追加
- CloudTrailログでどのAPI呼び出しが失敗しているかを特定
クロスアカウントデプロイの問題
症状
対処方法
- KMSキーのキーポリシーで両アカウントからのアクセスを許可
- デプロイ先アカウントのサービスロールに信頼関係を設定
- S3バケットポリシーでクロスアカウントアクセスを許可
- アーティファクトの暗号化設定を確認
パイプラインのパフォーマンス問題
実行時間が長すぎる
症状
対処方法
- 【ビルドの最適化】
キャッシュの活用、並列ビルド、ビルド環境のスペック向上
- 【テストの並列化】
複数のCodeBuildプロジェクトで並列実行
- 【不要なステップの削除】
必須でないステージやアクションを見直し
- 【段階的デプロイ】
Blue/Greenデプロイやカナリアデプロイで影響範囲を限定
頻繁なパイプライン実行
症状
対処方法
- トリガー設定を見直し（全てのpushではなく特定ブランチのみ）
- ポーリング間隔の調整
- 手動承認ステージの追加で不要なデプロイを防止
複数環境デプロイ特有の問題
環境間の設定ミス
症状
対処方法
- 環境変数の明確な分離（パラメータストア、Secrets Managerの活用）
- デプロイ前の設定値検証ステップを追加
- 環境ごとに異なるブランチ戦略を採用
- タグやパラメータで環境を明示的に指定
手動承認の見落とし
症状
対処方法
- SNS通知の設定で承認者に確実に通知
- 承認期限の設定
- 承認者の複数設定やエスカレーションフロー
- Slackなどのチャットツールとの連携
モニタリングとログ
ログの確認方法
問題の特定に必要なログ
- 【CodePipelineの実行履歴】
各ステージの成功/失敗状態
- 【CodeBuildログ】
ビルドプロセスの詳細（CloudWatch Logs）
- 【CloudFormationイベント】
スタック作成/更新の詳細
- 【CloudTrail】
API呼び出しの監査ログ
- 【アプリケーションログ】
デプロイ後のアプリケーション動作
アラートの設定
推奨される監視項目
- パイプライン失敗時のSNS通知
- ビルド失敗率の監視
- デプロイ所要時間の監視
- CloudWatch Eventsでパイプライン状態変更を検知
よくあるトラブルと対処
アーティファクトの破損
症状
- 次のステージでアーティファクトが見つからない、または破損している
対処方法
- S3バケットのバージョニング有効化
- アーティファクトの暗号化設定確認
- ステージ間のアーティファクト名の一致を確認
同時実行の競合
症状
対処方法
- パイプラインの実行モードを「QUEUED」に設定
- デプロイ対象リソースのロック機構実装
- 実行履歴の確認と不要な実行のキャンセル
ロールバック失敗
症状
対処方法
- Blue/Greenデプロイの採用で即座に切り戻し可能に
- CloudFormationのロールバック設定を有効化
- 以前のアーティファクトを保持しておき手動で再デプロイ
- バージョン管理された設定の保持