# Share a CDK Diff — The Change Set, Readable, at a URL

Canonical: https://commareports.com/share-cdk-diff
Published: 2026-09-14

> cdk diff shows the IAM and security-group changes that matter and buries them in a CI log. Render it to HTML, publish to Comma, and get approval anchored on the resource.

# Share a CDK diff

`cdk diff` is unusually good output. It separates the change set into ordinary
resource updates and a security section — IAM statement changes, security group
rule changes — because those are the ones that need a human. CDK will even
refuse to deploy without an explicit approval when that section is non-empty.

Then the output goes to a CI log, which flattens colour, truncates in some
viewers, and requires a login. The approval prompt fires against a document
nobody read.

## Render it, keep the colour

```bash
cdk diff --color=always MyStack 2>&1 | ansi2html --scheme=xterm > cdk-diff.html
```

`ansi2html` (`pip install ansi2html`) turns the escape sequences into styled
HTML instead of discarding them, which preserves the visual separation between
`[+]`, `[-]`, `[~]` and the IAM block. `2>&1` because CDK writes the diff to
stderr.

For structured output, `cdk diff --json` gives you the change set as data, which
is worth rendering when you want IAM changes pinned to the top rather than
wherever CloudFormation happened to order them.

## Publish it per pull request

```bash
cdk diff --color=always MyStack 2>&1 | ansi2html > cdk-diff.html

REPORT=$(curl -fsS -X POST "https://commareports.com/api/v1/reports" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html cdk-diff.html \
        --arg t "CDK diff — MyStack — PR #$PR_NUMBER" '{title: $t, html: $html}')")

echo "Plan: $(echo "$REPORT" | jq -r .url)" >> "$GITHUB_STEP_SUMMARY"
```

A new report per PR, because the diff belongs to a proposed change. See the
[API reference](/docs/api) and [publishing from CI](/docs/ci).

This also side-steps the failure mode of diff-bot comments: GitHub truncates
long comments, and the diffs that get truncated are precisely the large ones
that needed reading.

## Approve on the resource, not on the code

A CDK pull request diff is TypeScript. The risk is in the synthesized
CloudFormation, and the two do not look alike — a one-line change to a
construct prop can replace a resource.

Publishing the diff puts approval where the risk is. Anchored threads carry the
specific objection:

- "This replaces the RDS instance — snapshot first."
- "This IAM statement adds `s3:*` on all buckets. Scope it."
- "Approved for the 02:00 window."

See [commenting on HTML](/comment-on-html) and
[sharing & access control](/docs/sharing).

## Keep it restricted

A CDK diff names account ids, ARNs, subnet and security-group ids, and the
shape of your network. Set access to private or team — never link-anyone.

## Limits

- **Entry HTML: 5 MB.** A multi-stack app's full diff can exceed it — diff per
  stack, which is how it gets reviewed anyway.
- Assets: 25 MB per file, **250 MB and 500 files total**.
- **60 requests/minute per token.**

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision
history.

**[Publish a diff →](https://commareports.com/)**

### Related

- [Share a Terraform plan](/share-terraform-plan) · [Share a Pulumi preview](/share-pulumi-preview)
- [Share an Infracost report](/share-infracost-report) · [Share a Checkov report](/share-checkov-report)
- [Share a Prowler report](/share-prowler-report) · [Share an Ansible report](/share-ansible-report)