Usage Examples

Practical workflow examples for the AWS CDK Diff GitHub Action, from simple single-environment setups to reusable workflow patterns.

These examples show different ways to integrate the AWS CDK Diff GitHub Action into your workflows. Start with the complete workflow example, then explore reusable patterns as your needs grow.

Want to see these in action? The AWS CDK Starter Kit has a working workflow you can fork and test immediately.

1. Complete Workflow

The simplest setup that covers most use cases. Posts a single CDK diff comment to each Pull Request.

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

What this does:

  1. Triggers on Pull Requests targeting main
  2. Checks out the PR branch (using the PR head SHA)
  3. Authenticates with AWS using OIDC
  4. Installs dependencies
  5. Runs cdk diff and captures output
  6. Posts the formatted diff as a PR comment

Key details:

  • The --no-color flag ensures clean parsing
  • The || true prevents workflow failure if diff exits with non-zero
  • The 2>&1 captures both stdout and stderr

2. Reusable Workflow

When you're running the same workflow across multiple repositories, reusable workflows help you maintain consistency and reduce duplication.

Step 1: Create the Reusable Workflow

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

Step 2: Call It From Your Main Workflow

Create or update .github/workflows/cdk-diff.yml:

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
    # For same-repo, use: ./.github/workflows/post-cdk-diff-comment.yml
    # For cross-repo, use: your-org/your-repo/.github/workflows/post-cdk-diff-comment.yml@main
    uses: ./.github/workflows/post-cdk-diff-comment.yml
    with:
      diff-file: cdk-diff-output.txt
      aws-region: us-east-1

Why use reusable workflows?

  • Separation of concerns - AWS auth stays in the generating job, PR commenting in another
  • Different permissions - Jobs can have exactly the permissions they need
  • Artifact sharing - Pass the diff file between jobs
  • Centralized logic - Update once, apply everywhere
  • Composable - Combine with deployment workflows easily

Tips for Both Patterns

File naming: The diff file name doesn't matter, just keep it consistent between generation and posting.

Error handling: The || true after cdk diff is important. CDK diff returns non-zero if changes exist, which would fail your workflow without it.

Caching: Both examples use cache: npm in the Node.js setup. This speeds up subsequent runs significantly.

For more options, check the Configuration reference for all available inputs and outputs.

← InstallConfiguration →