Inputs & Outputs

Quick Reference

Use these tables for a quick overview of all available inputs and outputs. Scroll down for detailed explanations and examples.

Inputs

Outputs

Inputs Explained

Below you'll find detailed explanations for each input parameter, including usage examples, best practices, and common use cases.

diff-file

Required: Yes Type: String Description: Path to the CDK diff output file to post as a comment in the Pull Request.

The file should contain the raw output from running cdk diff. Typically, you'll redirect the command output to a file:

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

Important notes:

• Use the --no-color flag to ensure clean parsing
• Redirect both stdout and stderr using 2>&1
• Add || true to prevent the step from failing if the diff exits with a non-zero status

Example:

- uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: cdk-diff-output.txt

token

Required: No Type: String Default: ${{ github.token }} Description: The GitHub or Personal Access Token (PAT) to use for posting comments to Pull Requests.

The default github.token works for most cases. Use a custom PAT if you need elevated permissions or cross-repository access.

Example with custom token:

- uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: cdk-diff-output.txt
    token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

When to use a custom token:

• Posting comments from a bot account
• Cross-repository workflows
• Organizations with strict token policies

Setup: Add your custom token as a repository secret in Settings > Secrets and variables > Actions. See the custom token usage example for detailed setup steps.

header

Required: No Type: String Description: Set a custom header to use for the Pull Request comment.

This is particularly useful when running multiple CDK diff comments in the same PR for different environments or stacks. The action uses the header to identify and update the correct comment.

Example:

- uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: dev-diff.txt
    header: "Dev Environment"
    aws-region: us-east-1

- uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: prod-diff.txt
    header: "Production Environment"
    aws-region: eu-west-1

Without a custom header:

CDK Diff Results

With a custom header:

CDK Diff Results - Dev Environment

aws-region

Required: No Type: String Description: The AWS region where the infrastructure changes are being applied (e.g., us-east-1, eu-west-1).

When provided, the region is displayed in the PR comment header to help teams understand which AWS region the changes will affect.

Example:

- uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: cdk-diff-output.txt
    aws-region: us-east-1

Comment header with region:

CDK Diff Results
AWS Region: us-east-1

Common use case: Multi-region deployments where different stacks target different regions.

Outputs Explained

The action provides two outputs that you can use in subsequent workflow steps for conditional logic, notifications, or further processing.

markdown

Type: String Description: The raw markdown output of the formatted cdk diff command.

Use this output to pass the formatted diff to other workflow steps or actions for additional processing.

Example:

- name: Post CDK Diff Comment
  id: cdk-diff
  uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: cdk-diff-output.txt

- name: Process Diff Output
  run: |
    echo "Markdown output:"
    echo "${{ steps.cdk-diff.outputs.markdown }}"

Common use cases:

• Logging the diff for debugging
• Sending the diff to external systems (Slack, email, etc.)
• Custom post-processing or analysis

empty

Type: String (boolean as string) Values: 'true' or 'false' Description: Indicates whether the cdk diff contains any infrastructure changes.

When 'true', the diff shows no changes (empty). When 'false', the diff contains changes. Note that GitHub Actions outputs are always strings, so you'll need to compare against string values.

Example:

- name: Post CDK Diff Comment
  id: cdk-diff
  uses: towardsthecloud/aws-cdk-diff-pr-commenter@v1
  with:
    diff-file: cdk-diff-output.txt

- name: Check for Changes
  if: steps.cdk-diff.outputs.empty == 'false'
  run: echo "Infrastructure changes detected!"

- name: No Changes
  if: steps.cdk-diff.outputs.empty == 'true'
  run: echo "No infrastructure changes."

Common use cases:

• Conditional workflow steps based on whether changes exist
• Failing the workflow if unexpected changes are detected
• Triggering notifications only when changes are present
• Skipping deployment steps when there are no changes

Input validation

The action performs the following validation:

• diff-file: Must be a valid file path. The action will fail if the file doesn't exist or can't be read.
• token: Must be a valid GitHub token with pull-requests: write permission.
• header: Accepts any string value (no validation).
• aws-region: Accepts any string value (no validation for valid AWS region format).

Permissions required

Regardless of which inputs you use, the workflow must have these minimum permissions:

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

If using AWS OIDC authentication (recommended):

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

For more details on setting up permissions, see the Install guide.