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

[badmintoncryer]

概要

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）を選択して有効化する。

[konokenj]

ご提案ありがとうございます。私もCDを実装したくなるケースは多く、確かにニーズはあると思います。

CDKでやるべき範囲

初心者の認知負荷を考えると、スタックが増えるのは避けたいです。OIDC Providerについては「なかったら作る」が必要で、かつ、ポリシーにリポジトリなどを含める必要があるので、これはCDK管理外でもいいのではないでしょうか。

懸念: 継続的なCDのテスト

aws-samples としてワークフローファイルを置くならその動作は継続的に検証されているべきですが、純粋なCDだと状態を持ってしまうため難しいです。かわりに、CDKの integ-runner のようにスナップショットの差分があるときだけdeploy -> test -> destroyをするようなワークフローならサンプルとしても品質担保に有用です。ユーザーとしては destroy 部分を削除すればそのままCDとして使えます。ただ、メンテナンスコストは重いのでstarter-kitの性質上どこまでやるべきか悩ましいです。

ご意見ください。

[badmintoncryer]

@konokenj コメントありがとうございます！

これはCDK管理外でもいいのではないでしょうか。

異論ありません。私もOIDC連携用のAWSリソース群はIaC管理外にすることも多いです。
代替として、これらのリソースのaws cliによる構築方法だけREADMEに記載したいと思いました。

スナップショットの差分があるときだけdeploy -> test -> destroyをするようなワークフローならサンプルとしても品質担保に有用です。

actions workflowのテストがあったほうが好ましいのは間違いなく、ご提案頂いた方法は理にかなっていると思います！

僅かな懸念点は以下のとおりです。

• ユーザ側でのworkflowからのdestroy削除作業が必須になってしまう
• このリポジトリからデプロイするためのAWSアカウントが必要になる

actions workflowに関しては、一度動作検証したら挙動OKとして、テスト的な立ち位置のものを用意しないのも個人的には許容されると思っています。

テスト設置有無はどちらでも問題ないと思いますので、@konokenj さんの方で決定頂ければと思います！