deployment-pipeline

デプロイパイプライン

使用するタイミング

以下の場合にこのスキルを有効にします：

• GitHub Actions を使用した CI/CD パイプラインの設定または変更
• ステージング環境または本番環境へのアプリケーション変更のデプロイ
• 環境昇格戦略（dev -> staging -> production）の計画
• デプロイ前の検証ゲートの実装
• デプロイ済みサービスのヘルスチェックとスモークテストの設定
• デプロイ失敗後のロールバック手順の計画または実行
• カナリアデプロイまたはブルーグリーンデプロイ戦略の設定
• デプロイ失敗またはパイプラインエラーのトラブルシューティング

出力： デプロイ結果を deployment-report.md に記録します。ステータス、デプロイしたバージョン、ヘルスチェックの結果、および必要に応じてロールバック手順を含めてください。

以下の場合はこのスキルを使用しないでください：

• Docker イメージのビルドまたは最適化（docker-best-practices を使用）
• 本番環境のインシデントへの対応（incident-response を使用）
• モニタリングまたはアラートの設定（monitoring-setup を使用）
• インフラストラクチャのプロビジョニング（Terraform、CloudFormation）

手順

パイプラインのステージ概要

すべてのデプロイは、厳密な4段階のパイプラインに従います。どのステージも省略できません。

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────────┐
│  BUILD   │───>│   TEST   │───>│ STAGING  │───>│  PRODUCTION  │
│          │    │          │    │          │    │              │
│ • Lint   │    │ • Unit   │    │ • Deploy │    │ • Canary 10% │
│ • Build  │    │ • Integ  │    │ • Smoke  │    │ • Monitor    │
│ • Image  │    │ • E2E    │    │ • QA     │    │ • Full 100%  │
└──────────┘    └──────────┘    └──────────┘    └──────────────┘
     Gate:           Gate:           Gate:            Gate:
  Build pass     Tests pass     Smoke pass      Health checks
  No lint err    Coverage ≥80%  Manual approve  Error rate <1%

ステージ1：ビルド

ビルドステージでは、コード品質を検証し、デプロイ可能なアーティファクトを生成します。

手順：

1. Lint とフォーマットのチェック -- Python では ruff check と ruff format --check、React では eslint と prettier --check を実行します
2. 型チェック -- Python では mypy、TypeScript では tsc --noEmit を実行します
3. アーティファクトのビルド -- Python の wheel/sdist をビルドし、React の本番用バンドルをビルドします
4. Docker イメージのビルド -- git SHA とブランチ名をタグに設定します

ゲート条件： すべてのチェックが合格し、イメージが正常にビルドされること。

# GitHub Actions build stage
build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Lint Python
      run: ruff check src/ && ruff format --check src/
    - name: Type check Python
      run: mypy src/
    - name: Build backend image
      run: docker build -t app-backend:${{ github.sha }} -f Dockerfile.backend .
    - name: Build frontend
      run: npm ci && npm run build
    - name: Build frontend image
      run: docker build -t app-frontend:${{ github.sha }} -f Dockerfile.frontend .

ステージ2：テスト

テストスイート全体を実行します。「緊急」のデプロイであっても、テストを省略してはいけません。

手順：

1. 単体テスト -- pytest tests/unit/ -v --cov=src --cov-report=xml
2. 統合テスト -- pytest tests/integration/ -v（テスト用データベースが必要です）
3. フロントエンドテスト -- npm test -- --coverage
4. E2E テスト -- テスト環境に対して npx playwright test を実行します
5. セキュリティスキャン -- Python では pip-audit、Node では npm audit を実行します

ゲート条件： すべてのテストが合格し、カバレッジが80%以上で、重大な脆弱性がないこと。

# GitHub Actions test stage
test:
  needs: build
  runs-on: ubuntu-latest
  services:
    postgres:
      image: postgres:16
      env:
        POSTGRES_DB: testdb
        POSTGRES_PASSWORD: testpass
      ports: ['5432:5432']
    redis:
      image: redis:7-alpine
      ports: ['6379:6379']
  steps:
    - uses: actions/checkout@v4
    - name: Run unit tests
      run: pytest tests/unit/ -v --cov=src --cov-report=xml
    - name: Run integration tests
      run: pytest tests/integration/ -v
      env:
        DATABASE_URL: postgresql://postgres:testpass@localhost:5432/testdb
    - name: Check coverage threshold
      run: coverage report --fail-under=80

ステージ3：ステージング環境へのデプロイ

本番環境へのデプロイ前に検証するため、ステージング環境にデプロイします。

デプロイ前チェックリスト：

• CIですべてのテストが合格している
• データベースマイグレーションを scripts/migration-dry-run.sh でテスト済み
• ステージング環境の環境変数を確認済み
• フィーチャーフラグを適切に設定済み
• 依存サービスが利用可能であることを確認済み

手順：

1. マイグレーションのドライランを実行 -- ステージング DB クローンに対して Alembic マイグレーションを検証します
2. ステージング環境にデプロイ -- イメージをプッシュし、マイグレーションを適用して、サービスを再起動します
3. スモークテストを実行 -- ステージング URL に対して scripts/smoke-test.sh を実行します
4. ヘルスチェックを実行 -- すべてのエンドポイントに対して scripts/health-check.py を実行します
5. 手動 QA -- チームで重要なユーザーフローを検証します

ゲート条件： スモークテストが合格し、ヘルスチェックが正常で、QA の承認が得られていること。

ステージ4：本番環境へのデプロイ

本番環境へのデプロイでは、リスクを最小限に抑えるためにカナリア戦略を使用します。

カナリアデプロイの手順：

1. カナリアをデプロイ（トラフィックの10%） -- トラフィックの10%を新しいバージョンにルーティングします
2. 10分間モニタリング -- エラー率、レイテンシ、リソース使用量を監視します
3. カナリアを評価 -- エラー率が1%未満で、p99 レイテンシがベースラインの20%以内であれば、次に進みます
4. 50%まで拡大 -- トラフィックを50%に増やし、5分間モニタリングします
5. 全面展開（100%） -- デプロイを完了します
6. デプロイ後のスモークテスト -- スモークテストスイート全体を実行します

Canary Timeline:
  0 min    10 min   15 min   20 min
  |--------|--------|--------|
  10%      Check    50%      100%
  Deploy   Metrics  Ramp     Full
           OK?      Up       Rollout
           |
           No -> Rollback immediately

自動ロールバックのトリガー：

• カナリア実行中にエラー率が5%を超えた場合
• p99 レイテンシが50%を超えて増加した場合
• カナリアインスタンスでヘルスチェックが失敗した場合
• メモリ使用率が90%のしきい値を超えた場合

デプロイ前の検証

デプロイ前に、これらの検証を実行してください。ドライランには scripts/deploy.sh --validate-only を使用します。

バックエンドの検証：

# Verify migrations are consistent
alembic check

# Verify no pending migrations
alembic heads --verbose

# Test migration against staging clone
./skills/deployment-pipeline/scripts/migration-dry-run.sh \
  --db-url "$STAGING_DB_URL" \
  --output-dir ./deploy-validation/

# Verify all dependencies are pinned
pip-compile --dry-run requirements.in

フロントエンドの検証：

# Verify build succeeds
npm run build

# Check bundle size limits
npx bundlesize

# Verify environment variables are set
node -e "const vars = ['REACT_APP_API_URL']; vars.forEach(v => { if(!process.env[v]) throw new Error(v + ' not set') })"

環境の昇格

環境間で変更を移行する際は、厳格なルールに従う必要があります。

項目	開発	ステージング	本番
デプロイのトリガー	main へのプッシュ	テスト後に手動または自動	手動承認が必要
データベース	ローカル PostgreSQL	ステージング PostgreSQL	本番 PostgreSQL（RDS）
シークレット	.env ファイル	GitHub Secrets	AWS Secrets Manager
ログレベル	DEBUG	INFO	WARNING
フィーチャーフラグ	すべて有効	機能ごとに設定	段階的にロールアウト
SSL	自己署名	ACM 証明書	ACM 証明書
レプリカ数	1	2	3 以上（自動スケーリング）

昇格ルール：

1. コードは前の段階のすべてのゲートを通過する必要があります
2. データベースのマイグレーションは後方互換性を保つ必要があります（移行期間を設けずにカラムを削除してはいけません）
3. デプロイ前に環境変数を設定する必要があります
4. デプロイ前にフィーチャーフラグを正しい状態に設定する必要があります
5. 本番環境へのデプロイ前にロールバック計画を文書化する必要があります

ヘルスチェック

すべてのサービスでヘルスチェックエンドポイントを公開します。デプロイパイプラインは、デプロイのたびにこれらを検証します。

必須のヘルスチェックエンドポイント：

# FastAPI health check endpoints
@router.get("/health")
async def health():
    """Basic liveness check -- returns 200 if process is running."""
    return {"status": "healthy", "timestamp": datetime.utcnow().isoformat()}

@router.get("/health/ready")
async def readiness(db: AsyncSession = Depends(get_db)):
    """Readiness check -- verifies all dependencies are accessible."""
    checks = {}
    # Database
    try:
        await db.execute(text("SELECT 1"))
        checks["database"] = "ok"
    except Exception as e:
        checks["database"] = f"error: {str(e)}"
    # Redis
    try:
        await redis.ping()
        checks["redis"] = "ok"
    except Exception as e:
        checks["redis"] = f"error: {str(e)}"

    all_ok = all(v == "ok" for v in checks.values())
    return JSONResponse(
        status_code=200 if all_ok else 503,
        content={"status": "ready" if all_ok else "not_ready", "checks": checks}
    )

デプロイ時のヘルスチェック戦略：

After deploy:
  Wait 10s -> Check /health (liveness)
  Wait 5s  -> Check /health/ready (readiness)
  Wait 5s  -> Check /health/ready again (stability)
  All pass -> Deployment successful
  Any fail -> Trigger rollback

自動ヘルスチェック検証には scripts/health-check.py を使用します：

python scripts/health-check.py \
  --url https://staging.example.com \
  --retries 3 \
  --timeout 30 \
  --output-dir ./health-results/

ロールバック手順

デプロイに失敗した場合は、直ちに次のロールバック手順に従ってください。詳しい手順については、references/rollback-runbook.md を参照してください。

自動ロールバック（推奨）：

# Roll back to previous version
./skills/deployment-pipeline/scripts/deploy.sh \
  --rollback \
  --version "$PREVIOUS_VERSION" \
  --output-dir ./rollback-results/

ロールバック判断マトリックス：

シグナル	アクション	タイミング
エラー率 > 5%	自動ロールバック	即時
p99 レイテンシ > ベースラインの 2 倍	自動ロールバック	即時
ヘルスチェックの失敗	自動ロールバック	2 回の再試行後
ユーザーから報告された問題	手動でロールバックを判断	15 分以内
データの不整合	トラフィックを停止して調査	即時

データベースのロールバックに関する考慮事項：

• 前方のみのマイグレーションを推奨します。本番環境では alembic downgrade を避けてください
• マイグレーションを元に戻す必要がある場合は、変更を取り消す新しい前方マイグレーションを使用してください
• コード参照を削除するリリースと同時にカラムやテーブルを削除してはいけません
• 2 段階のアプローチを使用します：フェーズ 1 では新しいコードをデプロイし（後方互換性を維持）、フェーズ 2 で古いカラムを削除します

GitHub Actions CI/CD

CI/CD パイプライン全体は .github/workflows/deploy.yml で定義されています。完全なテンプレートについては、references/github-actions-template.yml を参照してください。

主なワークフロー機能：

• マトリックステスト -- Python 3.12 と 3.13 でテストします
• キャッシュ -- pip、npm、Docker レイヤーをキャッシュしてビルドを高速化します
• 並行実行制御 -- 新しいコミットが到着したときに、進行中のデプロイをキャンセルします
• 環境保護 -- 本番環境では手動承認を必須にします
• シークレット管理 -- 各段階で GitHub 環境のシークレットを使用します

# Key sections of the workflow
on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options: [staging, production]

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:    # Stage 1
  test:     # Stage 2 (needs: build)
  staging:  # Stage 3 (needs: test)
  production:  # Stage 4 (needs: staging, manual approval)

カナリアデプロイ

カナリアデプロイでは、全面展開の前に、トラフィックの一部を新しいバージョンへルーティングします。

Docker と Nginx による実装：

# nginx canary configuration
upstream backend {
    server backend-stable:8000 weight=9;   # 90% to stable
    server backend-canary:8000 weight=1;   # 10% to canary
}

カナリアの評価基準：

# Canary health evaluation
def evaluate_canary(metrics: dict) -> bool:
    """Return True if canary is healthy enough to proceed."""
    checks = [
        metrics["error_rate"] < 0.01,           # < 1% error rate
        metrics["p99_latency_ms"] < 500,         # p99 under 500ms
        metrics["memory_usage_pct"] < 85,        # Memory under 85%
        metrics["cpu_usage_pct"] < 75,           # CPU under 75%
        metrics["successful_health_checks"] >= 3, # 3+ consecutive passes
    ]
    return all(checks)

カナリアの監視チェックリスト：

• ベースラインと比較したエラー率（差が 1% 以内であること）
• ベースラインと比較したレイテンシのパーセンタイル（p50、p95、p99）
• リソース使用率（CPU、メモリ）がしきい値内であること
• ログのエラー量が増加していないこと
• ヘルスチェックエンドポイントが正しく応答していること
• 依存サービスのメトリクスが低下していないこと

デプロイメントスクリプト

次のスクリプトは、デプロイメントタスクを自動化します。

スクリプト	目的	使用方法
scripts/deploy.sh	デプロイメントの主要なオーケストレーション	./scripts/deploy.sh --env staging --output-dir ./results/
scripts/smoke-test.sh	デプロイ後のスモークテスト	./scripts/smoke-test.sh --url https://staging.example.com --output-dir ./results/
scripts/health-check.py	ヘルスエンドポイントの検証	python scripts/health-check.py --url https://staging.example.com --output-dir ./results/
scripts/migration-dry-run.sh	マイグレーションを安全にテスト	./scripts/migration-dry-run.sh --db-url $DB_URL --output-dir ./results/

クイックリファレンス

ステージング環境にデプロイ：

./skills/deployment-pipeline/scripts/deploy.sh \
  --env staging \
  --version $(git rev-parse --short HEAD) \
  --output-dir ./deploy-results/

本番環境にデプロイ（カナリア付き）：

./skills/deployment-pipeline/scripts/deploy.sh \
  --env production \
  --version $(git rev-parse --short HEAD) \
  --canary \
  --output-dir ./deploy-results/

スモークテストを実行：

./skills/deployment-pipeline/scripts/smoke-test.sh \
  --url https://staging.example.com \
  --output-dir ./smoke-results/

緊急ロールバック：

./skills/deployment-pipeline/scripts/deploy.sh \
  --rollback \
  --env production \
  --version $PREVIOUS_SHA \
  --output-dir ./rollback-results/

出力ファイル

デプロイメント結果を deployment-report.md に書き込みます。

# Deployment Report

## Summary

- **Environment:** staging | production
- **Version:** abc1234 (git SHA)
- **Status:** SUCCESS | FAILED | ROLLED_BACK
- **Timestamp:** 2024-01-15T14:30:00Z
- **Duration:** 12 minutes

## Pipeline Stages

| Stage | Status | Duration | Notes |
|-------|--------|----------|-------|
| Build | PASS | 3m | Image built: app:abc1234 |
| Test | PASS | 5m | 142 tests, 85% coverage |
| Staging | PASS | 2m | Smoke tests passed |
| Production | PASS | 2m | Canary 10% → 50% → 100% |

## Health Checks

- `/health` — 200 OK (12ms)
- `/health/ready` — 200 OK (45ms)

## Rollback Instructions

If issues occur, run:
\`\`\`bash
./scripts/deploy.sh --rollback --env production --version $PREV_SHA
\`\`\`

Previous version: def5678

## Next Steps

- Run `/monitoring-setup` to verify alerts are configured
- Run `/incident-response` if errors occur