GitHub Action cdk-synth-and-diff

Overview

The cdk-synth-and-diff action synthesizes AWS CDK templates and performs a diff against the base branch of a pull request. This helps detect destructive or unexpected changes early.

Prerequisites

• node@>=24 for github action runner

• aws-cdk must be installed

• Install the @shiftcode/iac-utilities package (version >=1.0.0) in the root of your repository. This package provides the stage-override-to-pr-base and aws-env-vars commands used by the action.

• The Action assumes that the repository is configured to use AWS CDK in the provided iacDir. Ensure that the specified directory contains a valid AWS CDK project.

Inputs

Name	Description	Required	Default Value
githubToken	GitHub token to use for the action	Yes
failOnDestructiveChanges	Whether or not destructive changes should fail the job	No	true
allowedDestroyTypes	Comma-delimited list of resource types that are allowed to be destroyed	No	""
iacDir	The location of the IAC package	No	packages/iac
cdkOutFilename	The name of the cdk.out file	No	pr-base.cdk.out
cloudFormationTemplate	The CloudFormation template to use for the diff	No	""

Usage

Below is an example of how to use the cdk-synth-and-diff action in a GitHub Actions workflow:

name: Example Workflow

on:
  pull_request:
    branches:
      - '**'

jobs:
  synth-and-diff:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Install Dependencies
        run: npm ci

      - name: CDK synth and diff with PR base branch stage
        if: github.event_name == 'pull_request'
        uses: shiftcode/cdk-synth-and-diff-action@SHA # vX.Y.Z
        with:
          failOnDestructiveChanges: false
          allowedDestroyTypes: 'AWS::ECS::TaskDefinition'
          githubToken: ${{ secrets.GITHUB_TOKEN }}
          cloudFormationTemplate: 'project-name-*'

Key Features

1. Stage Override: The action uses the stage-override-to-pr-base command to ensure the synthesized templates are based on the pull request's base branch.
2. Destructive Change Detection: The action can fail the job if destructive changes are detected, ensuring safe deployments.
3. Customizable Allowed Destroy Types: Consumers can specify resource types that are allowed to be destroyed during the diff process.

Outputs

The action does not produce any explicit outputs but provides diff results for the synthesized templates in form of a comment on the pull request.