Usage Examples

Learn how to incorporate the AWS CDK Diff GitHub Action into your CDK project workflows with practical examples for complete workflows and reusable workflows.

Overview

This page provides practical examples showing how to integrate the AWS CDK Diff GitHub Action into your CDK project's GitHub workflows. Each example demonstrates a different pattern, from a complete workflow to reusable workflows for DRY patterns.

Use these examples as starting points and adapt them to your specific infrastructure and team requirements. All examples follow best practices for AWS authentication using OIDC and include proper permissions configuration.

Want a working example? Check out the AWS CDK Starter Kit. It's a production-ready CDK template with the GitHub Action already built into the workflow. Clone it to see how everything works together in a real project.

Example 1: Complete Workflow

The simplest setup posts a single CDK diff comment to Pull Requests:

name: CDK Diff on Pull Request

on:
  pull_request:
    branches:
      - main

jobs:
  post-cdk-diff-comment:
    name: Post CDK Diff Comment to PR
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      pull-requests: write
    env:
      AWS_REGION: us-east-1

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "22"
          cache: npm

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole  # Replace with your IAM role ARN
          aws-region: ${{ env.AWS_REGION }}

      - name: Install Dependencies
        run: npm ci

      - name: CDK Diff
        run: |
          npx cdk diff --all --no-color > cdk-diff-output.txt 2>&1 || true

      - name: Post CDK Diff Comment
        uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
        with:
          diff-file: cdk-diff-output.txt
          aws-region: ${{ env.AWS_REGION }}

This workflow:

  1. Triggers on Pull Requests to main
  2. Checks out the PR branch
  3. Authenticates with AWS using OIDC
  4. Installs dependencies
  5. Generates the CDK diff
  6. Posts the formatted diff as a PR comment

Example 2: Reusable Workflow

Create a reusable workflow for DRY patterns across multiple repositories.

First, create .github/workflows/post-cdk-diff-comment.yml:

name: Post CDK Diff Comment

on:
  workflow_call:
    inputs:
      diff-file:
        description: 'Path to the CDK diff output file'
        type: string
        required: true
      aws-region:
        description: 'AWS Region where resources are deployed'
        type: string

jobs:
  post-comment:
    name: Post CDK Diff Comment to PR
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5

      - name: Download CDK Diff
        uses: actions/download-artifact@v5
        with:
          name: cdk-diff-artifact

      - name: Post CDK Diff Comment
        uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
        with:
          diff-file: ${{ inputs.diff-file }}
          aws-region: ${{ inputs.aws-region }}

Then call this workflow from your main CDK diff workflow:

name: CDK Diff on Pull Request

on:
  pull_request:
    branches:
      - main

jobs:
  generate-cdk-diff:
    name: Generate CDK Diff
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    env:
      AWS_REGION: us-east-1

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Setup Node.js
        uses: actions/setup-node@v5
        with:
          node-version: "22"
          cache: npm

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole  # Replace with your IAM role ARN
          aws-region: ${{ env.AWS_REGION }}

      - name: Install Dependencies
        run: npm ci

      - name: CDK Diff
        run: |
          npx cdk diff --all --no-color > cdk-diff-output.txt 2>&1 || true

      - name: Upload CDK Diff
        uses: actions/upload-artifact@v5
        with:
          name: cdk-diff-artifact
          path: cdk-diff-output.txt

  post-cdk-diff-comment:
    name: Post CDK Diff Comment
    needs: generate-cdk-diff
    uses: ./.github/workflows/post-cdk-diff-comment.yml
    with:
      diff-file: cdk-diff-output.txt
      aws-region: us-east-1

Benefits:

  • Separates AWS authentication from PR commenting
  • Useful when different jobs need different permissions
  • Allows artifact reuse between jobs
  • Can be combined with deployment workflows
  • Centralized logic for consistency

For best practices, troubleshooting, and maintenance strategies, check out the Install guide.

← InstallConfiguration →