# cdk-diff-report

**See your AWS CDK infrastructure changes on every pull request.**

Runs `cdk diff` in CI and posts a clean summary of which resources are being
**added, modified, removed, and replaced** to your GitHub, GitLab, or Bitbucket
PR — updating the same comment on each push. Free and open source (MIT).

[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-CDK%20Diff%20Report-blue?logo=github)](https://github.com/marketplace/actions/cdk-diff-report)
![npm](https://img.shields.io/npm/v/cdk-diff-report)
![license](https://img.shields.io/npm/l/cdk-diff-report)

---

## What you get (free)

- A per-stack breakdown of added / modified / removed / **replaced** resources
- Posts to GitHub, GitLab, and Bitbucket - one comment, updated in place
- IAM / Security Group changes flagged for review
- Optional standalone HTML report as a CI artifact
- Works as a GitHub Action, an npm CLI, or a Node.js library

```
## CDK Diff Report

| ✅ Added | ⚠️ Modified | ❌ Removed | 🔄 Replaced | 🔐 IAM stacks |
|---------|------------|-----------|------------|--------------|
| 5       | 0          | 0         | 0          | 1            |

<details><summary><strong>MyStack</strong> — +5 · 🔐 IAM</summary>

| Change   | Logical ID  | Type        |
|----------|-------------|-------------|
| ✅ Added | MyBucket    | S3 › Bucket |
| ✅ Added | MyFunction  | Lambda › Function |
</details>
```

## Quick start (GitHub Action)

```yaml
name: CDK Diff
on: pull_request
jobs:
  cdk-diff:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - uses: dzon337/cdk-diff-report@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: eu-central-1
```

### npm CLI

```bash
npm install -g cdk-diff-report
cdk-diff-report              # run diff and post to your PR
cdk-diff-report --dry-run    # preview the markdown without posting
cdk-diff-report --cwd /path  # run from another directory
```

Config lives in `.cdkdiffreportrc` next to `cdk.json`:

```json
{ "platform": "github", "cdkArgs": ["--all"], "htmlOutput": "cdk-diff.html" }
```

| Option | Config key | Env var | Default |
|--------|-----------|---------|---------|
| Platform | `platform` | `CDK_DIFF_PLATFORM` | `bitbucket` |
| CDK args | `cdkArgs` | `CDK_DIFF_CDK_ARGS` | `--all` |
| HTML report | `htmlOutput` | `CDK_DIFF_HTML_OUTPUT` | — |
| Dry run | `dryRun` | `CDK_DIFF_DRY_RUN` | `false` |

Platform tokens: `GITHUB_TOKEN` (GitHub), `GITLAB_TOKEN` (GitLab),
`BITBUCKET_ACCESS_TOKEN` + `BITBUCKET_PR_ID` / `BITBUCKET_WORKSPACE` /
`BITBUCKET_REPO_SLUG` (Bitbucket). For AWS CodeBuild, GitLab MR pipelines, and
cross-repo setups, see the guides at [iacreview.com](https://iacreview.com) or
open a [discussion](https://github.com/dzon337/cdk-diff-report/discussions).

---

## 💎IaCReview - paid features at [iacreview.com](https://iacreview.com)

Upgrade your CDK diff workflow with the full **IaCReview** platform at
[iacreview.com](https://iacreview.com). Connect it by setting `IACREVIEW_API_KEY`
(get one at [iacreview.com](https://iacreview.com)); the CLI and Action light up
automatically.

### What you unlock

| Feature | Description                                                                                            |
|---------|--------------------------------------------------------------------------------------------------------|
|  **Cost estimation** | Monthly + annual cost delta per resource and per environment                                           |
|  **Security scanning** | Security findings mapped to your CDK source file                                                       |
|  **Policy enforcement** | Required tags, banned resource types, naming conventions - defined once in your dashboard              |
|  **Multi-environment analysis** | Accumulates different environments into one comment; replacements and data-loss risk called out first  |
|  **Merge verdict** | 🟢 READY / 🟡 REVIEW / 🔴 BLOCKED - can fail the pipeline on a blocked result                          |
|  **Rich PR comment** | The same comment, enriched with cost, security, policy, multi-env signals - all in one place           |
|  **AI analysis** | AI-powered review of your infrastructure changes with contextual recommendations                       |
|  **Personal account** | Your own account at [iacreview.com](https://iacreview.com) with PR tracking, run history, and settings |

>  **Get started →** [iacreview.com](https://iacreview.com)

---
## Use as a library

```ts
import { run, parseCdkDiff, generateMarkdownComment } from 'cdk-diff-report';

await run({ dryRun: true });
const diff = parseCdkDiff(rawCdkOutput);
console.log(diff.totalAdded, diff.totalReplaced);
```

| Export | Description |
|--------|-------------|
| `run(options)` | Full pipeline: diff → comment (delegates to the engine if connected) |
| `parseCdkDiff(raw)` | Parse `cdk diff` into structured data (incl. replacements) |
| `generateMarkdownComment(diff)` / `generateHtml(diff)` | Render the free comment / HTML |
| `runCdkDiff`, `readTemplates`, `resolvePrUrl`, `postComment` | CI/platform primitives |
| `resolveGitHubEnv` / `resolveGitLabEnv` / `resolveBitbucketEnv` + `upsert*` | Post directly to a PR/MR |

## License

MIT