AWS CDK × GitHub Actions 実践ガイド

みなさんこんにちは！
開発、楽しんでますかー？

私はめちゃくちゃ楽しんでます。

一昔前、
型落ちのタワーサーバーをネット通販で探して、
やっと届いた実機に夜な夜な CentOS をインストールしながら
地道に環境構築していた頃を思い返すと……
（それはそれで楽しかったですが。）

クラウドや IaC の登場で、
本当に “夢のような時代” になりましたよね。

これも CDK をはじめ、先人のエンジニアたちが築いてくれた
コミュニティの努力あってこそ。
いやはや、有り難いかぎりです。

そんな善意の活動に、私も微力ながら貢献したい。
そんな思いを込めて、今回の記事を書きました。
どうぞよろしくお願いします。

注）本記事はMac環境を想定しています。

さてさて、今回のテーマはと言うと…….

『で、どう使うの？』をコピペ解消する AWS CDK × GitHub Actions 実践ガイド

です。

CDK に限らず、新しい技術に触れたとき、

チュートリアルはやった
Hello World も動いた
……で、結局どう使うの？

そんな経験、ありませんか？

私はしょっちゅうあります！(キリッ！)

この記事では、

CDK のスタックをとりあえずデプロイしてみた！

という段階からもう一歩踏み込んで、

👉 GitHub Actions で AWS CDK のパイプラインを構築し、CI/CD の仕組みを爆速で整える

ところまで解説します。

擦りに擦られたテーマではあるのですが…….

CDK？聞いたことあるけど触ったことない。
チュートリアルだけやった。だけど実務ではまだ使ってない。

という方はもちろん、
CDK コミュニティの先輩方にも、
温かい目で読んでもらえたら嬉しいです。

それでは、続きをご覧ください！

1.アーキテクチャ

まずは全体アーキテクチャをざっくり押さえておきましょう。
特に CDK が何をしているのか理解すると、
後の CI/CD の理解が一気にスムーズになります。

CDK は JavaScript(TypeScript), Python, Java などのソースコードから
YAML/JSON 形式の CloudFormation テンプレートを生成します。
生成された CloudFormation テンプレートは既存の Stack と比較され、
CloudFormation が ChangeSet（差分）を作成します。
ChangeSet に問題がなければ、CloudFormation が既存の Stack をアップデートします。

これを読んで、

「え？これほぼ CloudFormation じゃない？」

と思った方は大正解！

CDK の正体は CloudFormation に対して

CloudFormationテンプレートをソースコード（TypeScript, Python など）で定義できるようにする

という付加価値をくっつけた『開発者のためのお助けツール』なのです。

言い換えると

CDK は CloudFormation の前段で、テンプレート生成・アセット管理・デプロイ準備までを担当する『高性能前処理ツール』であり、CloudFormation こそが本番のデプロイエンジンである

と言うわけです。

では今回のアーキテクチャにおいて、 GitHub Actions はどのような役割を担うのでしょうか？
一言でいうと次のようなことをします。

CDK のソースコードが入っている Git リポジトリへの Push をトリガーに GitHub Actions が起動し、cdk synth や cdk deploy を実行する。

意外とシンプルですよね？GitHub Actions そのものがインフラを作るわけじゃなくて、
CDK と CloudFormation の『デプロイコマンドを自動で叩いてくれる係』 という感じです。

図にするとこんな感じ。

改めてこの記事のゴールは

GitHub Actions で CDK のパイプラインを構築し、CI/CD の仕組みを爆速で整える

です。

ここまで読んでCDKの概要が掴めてきたみなさんは
何をすべきか、なんとなく想像がついているかもしれません。

やるべきことは次の２点です

AWS上にCDKを動かすための初期設定（Bootstrap & 必要なIAMロールの設定）をする
GitHub Actions で CDK と CloudFormation のデプロイコマンドを叩けるようにする

意外とシンプルですよね？

「なんだか出来そうな気がする。」

そんな気がしてきたらこちらのものです。

次の章からは実際に構築していきます。

💡この章のポイント：

CDK は CloudFormation の高性能前処理ツール
GitHub Actions では CDK と CloudFormation のデプロイコマンドを叩く

2.AWS側の準備

まずは AWS 上に CDK を動かすための環境構築をしていきましょう。
具体的には

CDK の初期設定（ Bootstrap ）を実行する
GitHub から OIDC接続をするための IAMロールを作る
OIDCプロバイダを作る

の３点を行います。

Step1 Bootstrap

Bootstrapを実行するには以下のコマンドを実行します。

cdk bootstrap aws://123456789012/ap-northeast-1

# アカウントIDとリージョンは次のように指定します。
# cdk bootstrap aws://<account-id>/<region>

Bootstrap を実行すると、指定したアカウント × リージョンに
CDKToolkit という名前の CloudFormation Stack が作成され、

CDKに必要な IAM ロール
アセット配置用の S3 バケット
（Docker 用の）ECR リポジトリ

などが準備されます。

ここでポイントなのが、

Bootstrap はアカウント × リージョンごとに1回ずつ実施する必要がある

という点です。

1.アーキテクチャの章で解説した通り、
CDK と CloudFormation ってとても深い関係にありましたよね？

CDK と深い関係にある CloudFormation がリージョンごとのサービスなので、
CloudFormation を使って色々なことをしようとすると、
リージョン単位で設定が必要になります。

だから CDK の初期設定コマンドである Bootstrap もリージョンごとに実施する必要がある、
というわけです。

余談ですがこのように、
サービスがグローバルなのかリージョンなのかそれとも AZ なのか
を意識すると、 AWS への理解がいっそう深まると思います。

Step2 IAMロール

続いて、 GitHub からアクセスするための認証情報を準備しましょう。

「IAM ユーザーを作って、セキュリティ認証情報でアクセスキーを作成して...」

って、ついつい楽したくなっちゃいますが、ここは我慢です。

アクセスキーを使った認証は直感的ですし、一見楽に見えるのですが、
使わなくなったキーを削除するまでのライフサイクルを考えると、
きちんと管理するのが結構手間なんですよね。

管理がずさんだと情報セキュリティの観点からも良くないですし。

ではどうするのか？というと、
この記事では IAM ロールと OIDC を使った認証をご紹介します。

IAM ロールと言うと 『何を』する権限を定義するモノ というイメージが強いと思います。
正確には IAM ロールにアタッチされている『許可ポリシー』 が、その権限の中身を定義しています。

次の例では、

sample-function という Lambda 関数の呼び出し（Invoke）を許可する

という権限が定義されています。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction"
      ],
      "Resource": [
        "arn:aws:lambda:ap-northeast-1:123456789012:function:sample-function"
      ]
    }
  ]
}

IAM ロールには、『何を』する権限以外にも、
もう一つ重要な『誰が』このロールを使えるか？
を定義することができます。

この『誰が』は IAM ロールの管理コンソールで
『信頼関係』のタブから確認できます。

次の例では、

123456789012 アカウントにある sample-rule という EventBridge ルールだけが、このロールを AssumeRole できる

という内容が定義されています。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "TrustEventBridgeService",
      "Effect": "Allow",
      "Principal": {
        "Service": "events.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012",
          "aws:SourceArn": "arn:aws:events:ap-northeast-1:123456789012:rule/sample-rule"
        }
      }
    }
  ]
}

今回作成するIAM ロールについては、
『何を』を定義する『許可ポリシー』には CDK のデプロイに必要な権限一式、
『誰が』を定義する『信頼関係』には GitHub のリポジトリを指定してあげれば良いわけです。

と言うわけで、新規作成したロールの『許可ポリシー』には
AdministratorAccess をアタッチします。

...このように強いポリシーをアタッチするのに違和感を感じる方がいるかもしれませんね。

その違和感大正解です！

CDK では、どんなサービスをデプロイするかによって
必要な権限が多岐にわたります。

まずは『デプロイを成功させること』を第一優先に考えて
最初のうちはこのように強いポリシーをアタッチするのも方法の一つです。

構成が固まってきたら、必要に応じてポリシーの内容を絞っていきましょう。

次に『信頼関係』についてですが、
OIDC 接続のためのフォーマットがありますので、
次の内容を参考に設定していきましょう。

例えば私（dellacraft）のアカウントにある sample という名前のリポジトリの
main ブランチからのデプロイを許可する場合は、次のようになります。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:dellacraft/sample:ref:refs/heads/main"
        }
      }
    }
  ]
}

Step3 OIDCプロバイダ

AWS側最後の設定です。
管理コンソールでIAMのメニューから
OIDCプロバイダを作成します。

この内容はテンプレなので、そのままコピーしちゃって大丈夫です。

項目	入力値
プロバイダのタイプ	OpenID Connect
プロバイダ URL	`https://token.actions.githubusercontent.com`
対象者（audience）	`sts.amazonaws.com`

ここまででAWS側の設定は完了です。

いかがでしょうか？
実際行ったのは３ステップだけ！
必要な工程は意外と少ないんですよね。

💡この章のポイント：

Bootstrap を実行して CDK の初期設定を行う（アカウント × リージョンごとに必要！）
GitHub Actions から CDK をデプロイするための IAM ロールを作成する
- 許可ポリシーにはまず AdministratorAccess をアタッチして、確実にデプロイを成功させる
  CDK の構成が固まったら、必要に応じて最小権限に絞る
- 信頼関係には、デプロイ元の GitHub リポジトリおよびブランチを
  OIDC に準拠したフォーマットで指定する
OIDCプロバイダを作成する

3.CDKの実装

さあ、いよいよ本題のCDKの実装です。
と言っても残りの作業はあと少し！

実はここまでの作業で、
山登りに例えると８合目まで登ってきています。

残る作業は次のとおり。

CDKアプリケーションを作成する
GitHub ActionsのYAMLを書く
リポジトリにpushする

もうひと頑張り！
順番に進めていきましょう。

Step4: CDKアプリケーション

CDKアプリケーションを作成するコマンドはとっても簡単
開発環境で以下のコマンドを叩くだけ。

# アプリケーション用のディレクトリ作る
mkdir sample

# ディレクトリに移動
cd sample/

# コマンド実行！
cdk init app --language typescript

既にAWS CLIをインストール済みの方はこれだけでOK！

じゃあ、AWS CLIが未インストールの場合は？

安心してください。
AWS CLIが未インストールの方や
（私もそうなんですが）開発環境を極力汚したくない方に
おすすめの方法をご紹介します。

mkdir sample

cd sample/

pnpm dlx aws-cdk init app --language typescript

このようにpnpmを使うことで、
開発環境を汚さずにCDKアプリケーションを作成できるのです。

GitHub Actions を使った CI/CD の構成であれば、
ローカルの環境はあんまり気にすることもないのですが、
開発環境をきれいに保ちたい方にはお勧めです。

さて、初期化したCDKアプリケーションの中身をみていきましょう。
ざっくりこんな感じのディレクトリ構成になっています。

sample/
├─ bin/
│  └─ sample.ts　# 重要！
├─ lib/
│  └─ sample-stack.ts　# 超重要！
├─ test/
│  └─ sample.test.ts
├─ cdk.json
├─ jest.config.js
├─ package.json
├─ tsconfig.json
└─ README.md

何やら『重要！』などとコメントされたファイルが２つありますね、

bin/sample.ts と lib/sample-stack.ts

の２つです。

この２つのファイルを押さえればCDKの基本的な構成が理解できます。
順に見てきましょう。

まずは『超重要！』と書かれた lib/sample-stack.ts から。
中身はこんな感じになっています。

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
// import * as sqs from 'aws-cdk-lib/aws-sqs';

export class SampleStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // The code that defines your stack goes here

    // example resource
    // const queue = new sqs.Queue(this, 'SampleQueue', {
    //   visibilityTimeout: cdk.Duration.seconds(300)
    // });
  }
}

cdk.Stack を継承しているクラスが定義されていますね。
Stack と聞いて、勘の言い方は気づいたかもしれませんが、
このクラスは CloudFormationStack の定義を記述するために用意されたクラスなんです。

このコンストラクタに色々なサービスの定義を記述していくのですが、
今回はデプロイの成功を目的としているので、
コメントに書かれた SQS Queue の定義を活用しちゃいましょう。

完成系がこちら。

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as sqs from 'aws-cdk-lib/aws-sqs';

export class SampleStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // The code that defines your stack goes here

    // example resource
    const queue = new sqs.Queue(this, 'SampleQueue', {
      visibilityTimeout: cdk.Duration.seconds(300)
    });
  }
}

次に、もう一つ『重要！』と書かれたファイルがありました。

bin/sample.ts です。

「さっきのファイルでスタックの定義したじゃん。他に何があるの？」

という疑問はおっしゃる通りなのですが、
実はこのファイルがあることによって、

複数のスタックを一つのCDKアプリケーションにまとめて管理できる

と言う恩恵を受けることができるんです。
CDKアプリケーションのdeployコマンドで最初に評価されるのもこのファイル。

main関数みたいなポジションだよと聞くと、
結構重要かも？って思えてきますよね？

ではファイルの中身を見てみましょう

#!/usr/bin/env node
import * as cdk from 'aws-cdk-lib';
import { SampleStack } from '../lib/sample-stack';

const app = new cdk.App();
new SampleStack(app, 'SampleStack', {
  /* If you don't specify 'env', this stack will be environment-agnostic.
   * Account/Region-dependent features and context lookups will not work,
   * but a single synthesized template can be deployed anywhere. */

  /* Uncomment the next line to specialize this stack for the AWS Account
   * and Region that are implied by the current CLI configuration. */
  // env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },

  /* Uncomment the next line if you know exactly what Account and Region you
   * want to deploy the stack to. */
  // env: { account: '123456789012', region: 'us-east-1' },

  /* For more information, see https://docs.aws.amazon.com/cdk/latest/guide/environments.html */
});

ここに書かれているは次の２点

cdk.App()のnew
SampleStack（lib/sample-stack.tsで定義したクラス）のnew

です。

SampleStackのコンストラクタにcdk.Appのインスタンス(app)を渡しています。
このappインスタンスによって複数のスタックを
一つのCDKアプリケーションでまとめて管理できるようになります。

スタックを追加する場合は、追加スタックのコンストラクタに
共通のappインスタンスを渡してあげればいいと言うわけです。

スタックの分け方については色々な宗派があるようですが、
私のお勧めは『極力分けない』です。

スタックを分けることで、管理の境界を明確にできる反面、
定義したサービス同士の参照が複雑になってしまって、
ズボラな私には管理のハードルが上がってしまうんですよね。

みなさんは状況に合わせて
ベターな分け方を模索してみてください。

Step5: GitHub Actions

最後に GitHub Actions の設定です。

今回はシンプルなワークフローを作成します。
次のようなファイルを作成し、リポジトリのルートに
.github/workflows/publish.yml として保存してください。

name: Deploy CDK Stack

on:
  push:
    branches:
      - main

permissions:
  id-token: write   # ← OIDC に必須
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      # 1. リポジトリのコードを取得
      - name: Checkout
        uses: actions/checkout@v4

      # 2. Node.js セットアップ
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24

      # 3. pnpm 有効化
      - name: Enable pnpm
        run: |
          corepack enable
          corepack prepare pnpm@10.22.0 --activate

      # 4. 依存関係インストール
      - name: Install dependencies
        run: pnpm install

      # 5. AWS 認証（OIDC で AssumeRole）※IAMロールのARNは適宜修正
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsCdkDeployRole
          aws-region: ap-northeast-1

      # 6. CDK Deploy
      - name: CDK Deploy
        run: pnpm dlx aws-cdk deploy --all --require-approval never

ここまでできたらあと一息！

作成したCDKプロジェクトをリポジトリにpushしましょう！
GitHub Actions が作成され、パイプラインが起動するはずです。

# gh（GitHub のCLI）がインストール済みなら飛ばしてください 
brew install gh

# GitHub にログイン
gh auth login

# CDKプロジェクトフォルダに移動
cd sample/

# commit_templateを作成
touch .commit_template

# ファイルをステージング
git add .

# 初回コミット
git commit -m "Initial commit CDK project"

# GitHub にリポジトリ作成
gh repo create --source=. --remote=origin --private

# main ブランチとして push
git push -u origin main

おめでとうございます！
これにて

GitHub Actions で CDK のパイプラインを構築し、CI/CD の仕組み

が無事整いました。

4.まとめ

この記事では

CDK のスタックをデプロイする

から一歩踏み込んで

CI/CDパイプラインを構築する

までの手順を紹介してきました。
いかがでしたでしょうか？

この記事を読んで、少しでも

「CDKの実務への展開がやりやすくなった！」

と感じてくれたらとても嬉しいです。

それでは、次回の記事でお会いしましょう！

付録1.よくあるつまづきポイント

ここではよくあるつまづきポイントをまとめました。
うまくいかないときは次のポイントを見直してみてください。

1. AWS 編

Bootstrap はデプロイするアカウント × リージョンで実施していますか？
- Bootstrap はアカウント × リージョンごとに必要です。
GitHub Actionsが使うIAM ロールの『許可ポリシー』と『信頼関係』は正しいですか？
- 『許可ポリシー』には AdministratorAccess をアタッチします。
- 『信頼関係』は OIDC のフォーマットで GitHub Actions からのアクセスを許可します。
OIDCプロバイダは作成しましたか？
- 管理コンソールでIAMの画面からStep3: OIDCプロバイダを作成しましょう。

2. CDK 編

lib/sample-stack.ts の内容は正しいですか？
- 必要なライブラリは import されていますか？
- CDK V2 の場合、cdk の import はimport * as cdk from 'aws-cdk-lib';です。必要に応じて修正しましょう。
bin/sample.ts の内容は正しいですか？
- 必要なスタックは new されていますか？
- CDK V2 の場合、cdk の import はimport * as cdk from 'aws-cdk-lib';です。必要に応じて修正しましょう。
workflow.yml の位置は正しいですか？
- 正しいファイルパスは.github/workflows/publish.ymlです。
workflow.yml の内容は正しいですか？
- 必要に応じてStep5: GitHub Actionsをみかえしてみてください。

3. GitHub 編

Push 先の GitHub リポジトリは正しいですか？
- Step2: IAMロールで指定したリポジトリと合わせましょう。
commit_templateがないと言われた
- .commit_templateと言うファイルをルートに作成します。中身は空でOK！

4. その他

環境を消したくなったら？
- CloudFormationStackからCDKで作成したスタックを削除すればOKです！

付録2.要点まとめ（チートシート）

本記事の内容を最小の手順・最短の理解で再現できるようまとめました。
時間のない方は、ここだけ見れば CDK × GitHub Actions の基本構築ができます。

1. Bootstrap（デプロイ先アカウント × リージョンで1回だけ実行）

cdk bootstrap aws://123456789012/ap-northeast-1

どこで実行するか迷ったら 👉 AWS CloudShell がおすすめ！

2. GitHub Actions 用 IAM ロールを作成

許可ポリシー：まずは AdministratorAccess（後で絞ればOK）
信頼関係（Trust Policy）：GitHub OIDC を許可する設定

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:dellacraft/sample:ref:refs/heads/main"
        }
      }
    }
  ]
}

3. OIDC プロバイダを IAM に作成

URL：https://token.actions.githubusercontent.com
audience：sts.amazonaws.com

4. CDK アプリケーションの初期化

# アプリケーション用ディレクトリ
mkdir sample
cd sample/

# CDK 初期化（開発環境を汚さない安全版）
pnpm dlx aws-cdk init app --language typescript

5. CDK コードの修正

bin/sample.ts：App と Stack の new を確認
lib/sample-stack.ts：必要な import（特に v2 の aws-cdk-lib）

6. GitHub Actions（deploy.yml）の配置と内容

パス：.github/workflows/publish.yml

name: Deploy CDK Stack

on:
  push:
    branches:
      - main

permissions:
  id-token: write   # ← OIDC に必須
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Enable pnpm
        run: |
          corepack enable
          corepack prepare pnpm@10.22.0 --activate

      - name: Install dependencies
        run: pnpm install

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsCdkDeployRole
          aws-region: ap-northeast-1

      - name: CDK Deploy
        run: pnpm dlx aws-cdk deploy --all --require-approval never

7. GitHub リポジトリ作成 → Push

# gh が未インストールなら
brew install gh

# GitHub にログイン
gh auth login

cd sample/

# 空のcommit_templateを作成
touch .commit_template

# コミット
git add .
git commit -m "Initial commit CDK project"

# GitHub にリポジトリ作成
gh repo create --source=. --remote=origin --private

# main ブランチとして push
git push -u origin main

8. 完了！

以上で CDK × GitHub Actions による自動デプロイ（爆速 CI/CD）が構築できます。

付録3. ソースコード（GitHub リポジトリ）

この記事で解説した構成（CDK / GitHub Actions / OIDC）の
最低限のサンプルを GitHub に公開しています。

デプロイの実行ロール、OIDC の信頼関係、Bootstrap など
全ステップが再現できるようになっています。

📦 GitHub リポジトリ
https://github.com/dellacraft/qiita-sample-cdk