How do I turn cdk diff into a shareable report?

`cdk diff --color=always 2>&1 | ansi2html > cdk-diff.html` preserves the colour coding that distinguishes additions, removals and the IAM statement changes. Publish the HTML to Comma for a URL.

Why does the colour matter?

cdk diff uses it to separate the security-relevant section — IAM statement changes and security group rules — from ordinary resource updates. Stripped to plain text, the most important part of the output looks the same as the least.

Can I publish the diff per pull request?

Yes. POST a new report per PR and put the URL in the PR body, so the plan being approved is a document rather than a log fold nobody expanded.

Does this replace cdk-diff PR bots?

It complements them. A bot comment truncates at GitHub's comment limit on exactly the large diffs that need reading; a link does not truncate and takes anchored comments.

Should the report be public?

No. A diff names account ids, ARNs, security group rules and VPC layout. Keep access private or team.

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

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

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 and publishing from 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 and sharing & access control.

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 →