Install

In this guide, you'll set up the AWS CDK Diff GitHub Action and post your first diff comment to a Pull Request. Takes about 10 minutes.

Requirements

Before you start, make sure you have:

How It Works

Here's what the workflow does:

Permissions

Your workflow needs these permissions:

permissions:
  contents: read        # Read repository contents
  pull-requests: write  # Post comments on PRs

Using AWS OIDC authentication (recommended)? Add id-token: write:

permissions:
  contents: read
  id-token: write       # Required for AWS OIDC authentication
  pull-requests: write

Step 1: Create the Workflow File

Create .github/workflows/cdk-diff.yml in your repository:

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
          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 }}

Step 2: Update Placeholder Values

Replace these values in your workflow:

Don't have an IAM role for GitHub Actions yet? Check out the guide on configuring OpenID Connect for GitHub in AWS CDK.

Step 3: Test It

1. Create a branch: git checkout -b test-cdk-diff
2. Make a change to one of your CDK stacks
3. Push and open a PR: git push origin test-cdk-diff
4. Watch the action run and check for the diff comment

The comment shows:

• IAM statement changes (if any)
• Security Group changes (if any)
• Parameter changes (if any)
• Resource changes (additions, updates, removals)

No infrastructure changes? The action skips posting to keep your PR clean.

Try Before You Set Up

Want to see it work before configuring your own repo? Fork the AWS CDK Starter Kit. It has this workflow pre-configured. Open a PR with infrastructure changes and watch the action run.

Best Practices

Workflow Organization

• Separate concerns - Keep diff generation and deployment in separate workflows
• Use reusable workflows - Centralize your workflow logic for consistency across repos
• Fail gracefully - Always use || true with cdk diff to prevent step failures
• Enable parallelism - Use job matrices when running multiple environment diffs

Security

• Use OIDC over access keys - Short-lived credentials are more secure
• Minimize permissions - Only grant what the workflow actually needs
• Protect sensitive data - Don't expose account IDs or role ARNs in public repos
• Enable CloudTrail - Audit all CDK operations

Performance

• Cache dependencies - Use actions/cache for npm packages and CDK assets
• Run environments in parallel - Don't sequence what can run concurrently
• Use conditional execution - Skip steps that don't apply with if conditions

Maintenance

• Pin action versions - Use @v1 instead of @main for stability
• Set up alerts - Get notified when workflows fail
• Keep dependencies updated - Regularly update the action and your CDK version
• Document customizations - Comment any non-standard configurations

Troubleshooting

Comment not appearing

What you see: Workflow succeeds but no comment on the PR.

Check these:

• pull-requests: write permission is set
• Workflow triggers on pull_request events
• diff-file path matches your actual output file
• GitHub token has correct permissions

Diff output looks wrong

What you see: Comment shows raw text instead of formatted sections.

Check these:

• Using --no-color flag with cdk diff
• Redirecting both stdout and stderr: > file.txt 2>&1
• File actually contains CDK diff output (not empty or error messages)

Multiple comments on same PR

What you see: New comment appears instead of updating the existing one.

Check these:

• Using consistent header values across workflow runs
• Not changing the header between commits
• Action version is the same across runs

AWS authentication fails

What you see: Cannot assume IAM role or access AWS resources.

Check these:

• IAM role ARN is correct
• Trust relationship allows your GitHub repository
• id-token: write permission is set
• OIDC identity provider is configured in AWS

Workflow runs slow

What you see: Takes too long to complete.

Try these:

• Enable npm dependency caching
• Use job matrices for parallel execution
• Cache CDK synthesis output
• Reduce number of stacks per workflow

What's Next

• Configuration reference - All available inputs and outputs
• Usage examples - Multi-environment diffs, reusable workflows, and more
• CloudBurn App - Add cost analysis to your CDK diffs

Need more help? Check the GitHub Marketplace page or the source repository for issues and discussions.