feat: GitHub Actions OIDC連携による自動デプロイ環境の構築

Read the existing build.yml workflow and the implementation for #108 before tracing the CDK entry points for GitHubOidcStack. Use .github/workflows/deploy.yml and the OIDC stack requirements in this issue as the acceptance checklist; done means the manual template, environment roles, and setup documentation work without long-lived AWS credentials.

概要

GitHub Actions と AWS IAM OIDC 連携を使った自動デプロイパイプラインのテンプレートを追加する。
永続的なAWSクレデンシャルを使わず、OIDC短期トークンで安全にデプロイを実行する。

本リポジトリはテンプレートであるため、ワークフローは workflow_dispatch（手動実行）のみをデフォルトとし、
ユーザーがコピー後に push / tag トリガーを自身の運用に合わせて有効化する想定。

Depends on #108（マルチ環境デプロイ対応）

背景・モチベーション

現状は手動で cdk deploy を実行する必要があり、以下の課題がある：

• デプロイの属人化（誰がいつデプロイしたか追跡しにくい）
• IAMユーザーの長期クレデンシャル管理のセキュリティリスク
• CI（build.yml）はあるがCDは未整備

このリポジトリはテンプレートとして利用されるため、コピー後すぐにCD環境を構築できる基盤を提供する。

設計方針

テンプレートとしての提供方針

このリポジトリ自体ではデプロイワークフローは実行されない。

• deploy.yml は workflow_dispatch（手動実行）のみをデフォルトトリガーとする
• push / tag トリガーはコメントで例示し、ユーザーが自身の運用に合わせて有効化する
• GitHubOidcStack はCDKコードとして含め、コピー後すぐに cdk deploy できるようにする

OIDCプロバイダーの制約への対応

AWSアカウントに対して GitHub 用 OIDC プロバイダー（https://token.actions.githubusercontent.com）は
1アカウントにつき1つしか作成できない。
そのため、OIDCプロバイダーは専用スタック GitHubOidcStack に分離し、
環境ごとの権限分離は IAMロールの Trust Policy の sub 条件（ブランチ/タグ）で実現する。

GitHubOidcStack（1回だけデプロイ）
├── OIDC Provider（1つ）
├── IAM Role for dev  ← sub: repo:OWNER/REPO:ref:refs/heads/develop（方式A/C）
│                        sub: repo:OWNER/REPO:ref:refs/tags/dev-v*（方式B）
└── IAM Role for prod ← sub: repo:OWNER/REPO:ref:refs/heads/main（方式A）
                         sub: repo:OWNER/REPO:ref:refs/tags/v*（方式B/C）

既にOIDCプロバイダーが存在するアカウントでは --context existingOidcProvider=true で
新規作成をスキップし、既存プロバイダーを参照可能にする。

デプロイトリガー方式

ワークフローはデフォルトで workflow_dispatch のみとし、以下3方式をコメントで例示する。
ユーザーがコピー後に自身の運用に合わせて選択・有効化する。

方式A: ブランチベース

develop ブランチ push → dev 環境に自動デプロイ
main ブランチ push    → prod 環境にデプロイ

• 向いているケース: 継続的デプロイ、高速イテレーション
• develop + main の2ブランチ運用が前提
• prod保護はブランチ保護ルール（マージに承認必須）で実現

方式B: タグベース（mainブランチ一本化）

dev-v* タグ push → dev 環境にデプロイ
v* タグ push     → prod 環境にデプロイ

• 向いているケース: リリースを明示管理したい、ブランチ戦略をシンプルにしたい
• main ブランチのみの運用で済む
• dev-v1.0.0-rc.1 → テスト → v1.0.0 という流れが自然
• 既存の release-please.yml との相性が良い

方式C: ハイブリッド

develop ブランチ push → dev 環境に自動デプロイ
v* タグ push         → prod 環境にデプロイ

• 向いているケース: devは常時デプロイしつつ、prodはリリース管理したい

GitHub Actions ワークフロー

# .github/workflows/deploy.yml
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy target environment'
        required: true
        type: choice
        options:
          - dev
          - prod

  ## ── ブランチベース（方式A）を有効化する場合、以下のコメントを外す ──
  # push:
  #   branches: [develop, main]

  ## ── タグベース（方式B）を有効化する場合、以下のコメントを外す ──
  # push:
  #   tags: ['dev-v*', 'v*']

  ## ── ハイブリッド（方式C）を有効化する場合、以下のコメントを外す ──
  # push:
  #   branches: [develop]
  #   tags: ['v*']

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars[format('AWS_ROLE_ARN_{0}', env.ENV_NAME)] }}
          aws-region: ${{ vars.AWS_REGION }}
      - run: |
          cd cdk
          npm ci
          npx cdk deploy --all --context env=$ENV_NAME --yes

変数は Repository Variables に設定：

• AWS_ROLE_ARN_DEV: dev用IAMロールARN
• AWS_ROLE_ARN_PROD: prod用IAMロールARN
• AWS_REGION: デプロイ先リージョン（例: ap-northeast-1）

補足: より厳密な環境保護が必要な場合は、GitHub Environments を設定し Required reviewers で prod デプロイに承認ゲートを追加できる。

セットアップ手順（ユーザー向けドキュメントに記載）

1. OIDCスタックのデプロイ（初回のみ）

cd cdk
npx cdk deploy GitHubOidcStack \
  --context githubOwner=YOUR_ORG \
  --context githubRepo=YOUR_REPO

2. GitHub リポジトリの設定

Repository Variables に以下を設定：

• AWS_ROLE_ARN_DEV: OIDCスタック出力値（dev用ロールARN）
• AWS_ROLE_ARN_PROD: OIDCスタック出力値（prod用ロールARN）
• AWS_REGION: デプロイ先リージョン（例: ap-northeast-1）

3. デプロイトリガーの有効化

deploy.yml 内のコメントから、自身の運用に合った方式（A/B/C）を選択して有効化する。