Install

Set up the AWS CDK Diff GitHub Action in your repository and post your first diff comment to a Pull Request.

Prerequisites

Before installing the AWS CDK Diff GitHub Action, ensure you have:

  • An existing AWS CDK project in a GitHub repository
  • Node.js installed (version 20 or higher recommended)
  • AWS credentials configured (via OIDC or access keys)
  • GitHub Actions enabled for your repository

Required permissions

The workflow running this action needs specific permissions to function correctly. Add these to your workflow file:

permissions:
  contents: read        # Required to read repository contents
  pull-requests: write  # Required to post comments on PRs

If you're using AWS OIDC authentication (recommended), you'll also need:

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

1) Create the workflow file

Create a new workflow file at .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 }}

2) Replace placeholder values

Update the following values in your workflow file:

  • IAM Role ARN: Replace arn:aws:iam::123456789012:role/GitHubActionsRole with your actual GitHub Actions IAM role ARN. If you don't have one set up yet, check out our guide on configuring OpenID Connect for GitHub in AWS CDK.
  • AWS Region: Change us-east-1 to your target AWS region if different.
  • Branch: Adjust the branches filter if your default branch isn't main.
  • Node.js version: Update the Node.js version to match your project requirements.

3) Test the action

Create a test Pull Request that modifies your CDK infrastructure:

  1. Create a new branch: git checkout -b test-cdk-diff
  2. Make a change to one of your CDK stacks
  3. Commit and push: git push origin test-cdk-diff
  4. Open a Pull Request against your main branch

The action will run automatically and post a comment with the CDK diff output. The comment will show:

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

4) Verify the output

Check your Pull Request for a new comment from the GitHub Actions bot. The comment should contain:

  • A header identifying the diff
  • The AWS region (if configured)
  • Formatted sections for each type of change
  • A summary of all stack changes

If there are no infrastructure changes, the action will skip posting a comment to keep your PR conversations clean.

Try it out

Want to experiment without setting up your own workflow? Check out the AWS CDK Starter Kit. It's a production-ready CDK template with this workflow already configured. Fork it, open a Pull Request with infrastructure changes, and see the action in action.

Next steps

Best practices

Workflow organization

  1. Separate concerns: Keep diff generation and deployment in separate workflows
  2. Use reusable workflows: Create organization-level reusable workflows for consistency
  3. Fail gracefully: Always use || true with cdk diff to prevent step failures
  4. Enable parallel execution: Use job matrices or parallel jobs when possible

Security considerations

  1. Use OIDC over access keys: Always prefer AWS OIDC for authentication
  2. Minimize token permissions: Only grant required permissions to GitHub tokens
  3. Protect sensitive data: Never expose AWS account IDs or role ARNs in public repos
  4. Audit trail: Enable CloudTrail logging for all CDK operations

Performance optimization

  1. Cache dependencies: Use actions/cache for npm packages and CDK assets
  2. Parallel environments: Run multi-environment diffs in parallel
  3. Conditional execution: Skip unnecessary steps with if conditions
  4. Artifact reuse: Share artifacts between jobs instead of regenerating

Maintenance strategies

  1. Pin action versions: Use specific versions (@v1) instead of @main. Check the GitHub Marketplace for the latest stable release.
  2. Monitor workflow runs: Set up alerts for failed workflows
  3. Regular updates: Keep the action and dependencies updated
  4. Document customizations: Add comments explaining custom configurations

Troubleshooting

Comment not posting

Symptoms: Workflow succeeds but no comment appears on the PR.

Solutions:

  • Verify pull-requests: write permission is set
  • Check that the workflow is triggered on pull_request events
  • Ensure the diff-file path is correct
  • Verify the GitHub token has appropriate permissions

Diff output looks malformed

Symptoms: Comment shows raw text instead of formatted sections.

Solutions:

  • Use --no-color flag with cdk diff
  • Redirect both stdout and stderr: > file.txt 2>&1
  • Check that the diff file actually contains CDK diff output
  • Verify the file isn't empty

Multiple comments on the same PR

Symptoms: Multiple comments appear instead of updating the existing one.

Solutions:

  • Use consistent header values across workflow runs
  • Don't change the header between commits on the same PR
  • Check that the action version is consistent

AWS authentication failures

Symptoms: Cannot assume IAM role or access AWS resources.

Solutions:

  • Verify the IAM role ARN is correct
  • Check the trust relationship allows your GitHub repository
  • Ensure id-token: write permission is set
  • Validate the OIDC identity provider configuration

Performance issues

Symptoms: Workflow takes too long to complete.

Solutions:

  • Enable npm dependency caching
  • Use job matrices for parallel execution
  • Cache CDK synthesis output
  • Consider reducing the number of stacks or environments

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

← OverviewUsage Examples →