@jjrawlins/cdk-diff-pr-github-action 0.0.1-beta → 0.0.2-beta

package/.jsii

@@ -3548,7 +3548,7 @@
   },
   "name": "@jjrawlins/cdk-diff-pr-github-action",
   "readme": {
-    "markdown": "# cdk-diff-pr-github-action\n\nA small Projen-based helper library that wires a GitHub workflow to create a CloudFormation Change Set for a CDK stack on every pull request, then comments the formatted diff back on the PR. It also provides a ready‑to‑deploy IAM template you can use to grant the minimal permissions required for the workflow to create and inspect change sets.\n\nThis package exposes two constructs:\n\n- `CdkDiffStackWorkflow` — Generates one GitHub Actions workflow per stack that:\n  - Assumes your GitHub OIDC role\n  - Optionally chains into a separate CDK deploy role\n  - Runs `cdk deploy --no-execute` to create a change set\n  - Runs a generated script to render the change set as an HTML table and posts it to the PR and to the GitHub Step Summary\n  - Cleans up the change set\n\n- `CdkDiffIamTemplate` — Emits a CloudFormation template file (`cdk-diff-workflow-iam-template.yaml`) containing an example IAM role policy with the minimal permissions to create, describe, and delete CloudFormation change sets and read common CDK bootstrap resources. You can launch this in your account and then reference the created role.\n\n## Quick start\n\n1) Add the constructs to your Projen project (in `.projenrc.ts`).\n2) Synthesize with `npx projen`.\n3) Commit the generated files.\n4) Open a pull request — the workflow will create a change set and comment the diff.\n\n## Usage: CdkDiffStackWorkflow\n\n`CdkDiffStackWorkflow` renders a workflow per stack named `diff-<StackName>.yml` under `.github/workflows/`. It also generates a helper script at `.github/workflows/scripts/describe-cfn-changeset.ts` that formats the change set output and takes care of posting the PR comment and Step Summary.\n\nExample `.projenrc.ts`:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffStackWorkflow } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ... your usual settings ...\n  name: 'my-lib',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.85.0',\n  github: true,\n});\n\nnew CdkDiffStackWorkflow({\n  project,\n  // Stacks to diff on PRs\n  stacks: [\n    {\n      stackName: 'MyAppStack',\n      cdkDiffRoleToAssumeArn: 'arn:aws:iam::123456789012:role/cdk-diff-role',\n      cdkDiffRoleToAssumeRegion: 'us-east-1',\n      // Optional per‑stack OIDC override (if not using the defaults below)\n      // oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n      // oidcRegion: 'us-east-1',\n    },\n  ],\n  // Default OIDC role/region used by all stacks unless overridden per‑stack\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: Node version used in the workflow (default: '24.x')\n  // nodeVersion: '20.x',\n  // Optional: Yarn command to run CDK (default: 'cdk')\n  // cdkYarnCommand: 'cdk',\n  // Optional: Where to place the helper script\n  // scriptOutputPath: '.github/workflows/scripts/describe-cfn-changeset.ts',\n});\n\nproject.synth();\n```\n\n### Required properties\n- `project` (AwsCdkTypeScriptApp) — Your Projen project instance.\n- `stacks` (array) — One entry per CDK stack you want a diff for.\n- OIDC configuration: either\n  - Provide `oidcRoleArn` and `oidcRegion` at the top level, or\n  - Provide `oidcRoleArn` and `oidcRegion` on every stack item.\n\nIf neither the defaults nor all per‑stack values are supplied, the construct throws with a helpful error.\n\n### Stack item fields\n- `stackName` — The CDK stack name to create the change set for.\n- `cdkDiffRoleToAssumeArn` — The ARN of the role used to create the change set (role chaining after OIDC).\n- `cdkDiffRoleToAssumeRegion` — The region for that role.\n- `oidcRoleArn` (optional) — Per‑stack override for the OIDC role.\n- `oidcRegion` (optional) — Per‑stack override for the OIDC region.\n\n### What gets generated\n- `.github/workflows/diff-<StackName>.yml` — One workflow per stack, triggered on PR open/sync/reopen.\n- `.github/workflows/scripts/describe-cfn-changeset.ts` — A helper script that:\n  - Polls `DescribeChangeSet` until terminal\n  - Filters out ignorable logical IDs or resource types using environment variables `IGNORE_LOGICAL_IDS` and `IGNORE_RESOURCE_TYPES`\n  - Renders an HTML table with actions, logical IDs, types, replacements, and changed properties\n  - Prints the HTML, appends to the GitHub Step Summary, and (if `GITHUB_TOKEN` and `GITHUB_COMMENT_URL` are present) posts a PR comment\n\n### Environment variables used by the script\n- `STACK_NAME` (required) — Stack name to describe.\n- `CHANGE_SET_NAME` (default: same as `STACK_NAME`).\n- `AWS_REGION` — Region for CloudFormation API calls. The workflow sets this via the credentials action.\n- `GITHUB_TOKEN` (optional) — If set with `GITHUB_COMMENT_URL`, posts a PR comment.\n- `GITHUB_COMMENT_URL` (optional) — PR comments URL.\n- `GITHUB_STEP_SUMMARY` (optional) — When present, appends the HTML to the step summary file.\n- `IGNORE_LOGICAL_IDS` (optional) — Comma‑separated logical IDs to ignore (default includes `CDKMetadata`).\n- `IGNORE_RESOURCE_TYPES` (optional) — Comma‑separated resource types to ignore (e.g., `AWS::CDK::Metadata`).\n\n## Usage: CdkDiffIamTemplate\n\nAdd `CdkDiffIamTemplate` to your Projen project to emit an example IAM template you can deploy in your account:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ...\n});\n\nnew CdkDiffIamTemplate({ project });\n\nproject.synth();\n```\n\nThis will write `cdk-diff-workflow-iam-template.yaml` at the project root. The template defines:\n- A parameter `GitHubOIDCRoleArn` — pass the ARN of your existing GitHub OIDC role that will assume the change set role.\n- An IAM role `CdkChangesetRole` with minimal permissions for:\n  - CloudFormation Change Set operations\n  - Access to common CDK bootstrap S3 buckets and SSM parameters\n  - `iam:PassRole` to `cloudformation.amazonaws.com`\n- Outputs exporting the role name and ARN.\n\nYou can deploy the file via CloudFormation/StackSets and then use the created role ARN as the `cdkDiffRoleToAssumeArn` in your workflow configuration.\n\n## Testing\n\nThis repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:\n- Workflows are created per stack and contain all expected steps.\n- Only one script file is generated.\n- Per‑stack OIDC overrides are respected.\n- Helpful validation errors are thrown for missing OIDC settings.\n- The IAM template file contains the expected resources and outputs.\n\nRun tests with:\n\n```bash\nyarn test\n```\n\n## Notes\n- This package assumes your repository is configured with GitHub Actions and that you have a GitHub OIDC role configured in AWS.\n- The generated script uses the AWS SDK v3 for CloudFormation and posts comments using the GitHub REST API.\n"
+    "markdown": "# cdk-diff-pr-github-action\n\nA small Projen-based helper library that wires a GitHub workflow to create a CloudFormation Change Set for a CDK stack on every pull request, then comments the formatted diff back on the PR. It also provides a ready‑to‑deploy IAM template you can use to grant the minimal permissions required for the workflow to create and inspect change sets.\n\nThis package exposes two constructs:\n\n- `CdkDiffStackWorkflow` — Generates one GitHub Actions workflow per stack that:\n  - Assumes your GitHub OIDC role\n  - Optionally chains into a separate CDK deploy role\n  - Runs `cdk deploy --no-execute` to create a change set\n  - Runs a generated script to render the change set as an HTML table and posts it to the PR and to the GitHub Step Summary\n  - Cleans up the change set\n\n- `CdkDiffIamTemplate` — Emits a CloudFormation template file (`cdk-diff-workflow-iam-template.yaml`) containing an example IAM role policy with the minimal permissions to create, describe, and delete CloudFormation change sets and read common CDK bootstrap resources. You can launch this in your account and then reference the created role.\n\n## Quick start\n\n1) Add the constructs to your Projen project (in `.projenrc.ts`).\n2) Synthesize with `npx projen`.\n3) Commit the generated files.\n4) Open a pull request — the workflow will create a change set and comment the diff.\n\n## Usage: CdkDiffStackWorkflow\n\n`CdkDiffStackWorkflow` renders a workflow per stack named `diff-<StackName>.yml` under `.github/workflows/`. It also generates a helper script at `.github/workflows/scripts/describe-cfn-changeset.ts` that formats the change set output and takes care of posting the PR comment and Step Summary.\n\nExample `.projenrc.ts`:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffStackWorkflow } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ... your usual settings ...\n  name: 'my-lib',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.85.0',\n  github: true,\n});\n\nnew CdkDiffStackWorkflow({\n  project,\n  // Stacks to diff on PRs\n  stacks: [\n    {\n      stackName: 'MyAppStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::123456789012:role/cdk-diff-role',\n      changesetRoleToAssumeRegion: 'us-east-1',\n      // Optional per‑stack OIDC override (if not using the defaults below)\n      // oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n      // oidcRegion: 'us-east-1',\n    },\n  ],\n  // Default OIDC role/region used by all stacks unless overridden per‑stack\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: Node version used in the workflow (default: '24.x')\n  // nodeVersion: '20.x',\n  // Optional: Yarn command to run CDK (default: 'cdk')\n  // cdkYarnCommand: 'cdk',\n  // Optional: Where to place the helper script\n  // scriptOutputPath: '.github/workflows/scripts/describe-cfn-changeset.ts',\n});\n\nproject.synth();\n```\n\n### Required properties\n- `project` (AwsCdkTypeScriptApp) — Your Projen project instance.\n- `stacks` (array) — One entry per CDK stack you want a diff for.\n- OIDC configuration: either\n  - Provide `oidcRoleArn` and `oidcRegion` at the top level, or\n  - Provide `oidcRoleArn` and `oidcRegion` on every stack item.\n\nIf neither the defaults nor all per‑stack values are supplied, the construct throws with a helpful error.\n\n### Stack item fields\n- `stackName` — The CDK stack name to create the change set for.\n- `changesetRoleToAssumeArn` — The ARN of the role used to create the change set (role chaining after OIDC).\n- `changesetRoleToAssumeRegion` — The region for that role.\n- `oidcRoleArn` (optional) — Per‑stack override for the OIDC role.\n- `oidcRegion` (optional) — Per‑stack override for the OIDC region.\n\n### What gets generated\n- `.github/workflows/diff-<StackName>.yml` — One workflow per stack, triggered on PR open/sync/reopen.\n- `.github/workflows/scripts/describe-cfn-changeset.ts` — A helper script that:\n  - Polls `DescribeChangeSet` until terminal\n  - Filters out ignorable logical IDs or resource types using environment variables `IGNORE_LOGICAL_IDS` and `IGNORE_RESOURCE_TYPES`\n  - Renders an HTML table with actions, logical IDs, types, replacements, and changed properties\n  - Prints the HTML, appends to the GitHub Step Summary, and (if `GITHUB_TOKEN` and `GITHUB_COMMENT_URL` are present) posts a PR comment\n\n### Environment variables used by the script\n- `STACK_NAME` (required) — Stack name to describe.\n- `CHANGE_SET_NAME` (default: same as `STACK_NAME`).\n- `AWS_REGION` — Region for CloudFormation API calls. The workflow sets this via the credentials action.\n- `GITHUB_TOKEN` (optional) — If set with `GITHUB_COMMENT_URL`, posts a PR comment.\n- `GITHUB_COMMENT_URL` (optional) — PR comments URL.\n- `GITHUB_STEP_SUMMARY` (optional) — When present, appends the HTML to the step summary file.\n- `IGNORE_LOGICAL_IDS` (optional) — Comma‑separated logical IDs to ignore (default includes `CDKMetadata`).\n- `IGNORE_RESOURCE_TYPES` (optional) — Comma‑separated resource types to ignore (e.g., `AWS::CDK::Metadata`).\n\n## Usage: CdkDiffIamTemplate\n\nAdd `CdkDiffIamTemplate` to your Projen project to emit an example IAM template you can deploy in your account:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ...\n});\n\nnew CdkDiffIamTemplate({ project });\n\nproject.synth();\n```\n\nThis will write `cdk-diff-workflow-iam-template.yaml` at the project root. The template defines:\n- A parameter `GitHubOIDCRoleArn` — pass the ARN of your existing GitHub OIDC role that will assume the change set role.\n- An IAM role `CdkChangesetRole` with minimal permissions for:\n  - CloudFormation Change Set operations\n  - Access to common CDK bootstrap S3 buckets and SSM parameters\n  - `iam:PassRole` to `cloudformation.amazonaws.com`\n- Outputs exporting the role name and ARN.\n\nYou can deploy the file via CloudFormation/StackSets and then use the created role ARN as the `changesetRoleToAssumeArn` in your workflow configuration.\n\n## Testing\n\nThis repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:\n- Workflows are created per stack and contain all expected steps.\n- Only one script file is generated.\n- Per‑stack OIDC overrides are respected.\n- Helpful validation errors are thrown for missing OIDC settings.\n- The IAM template file contains the expected resources and outputs.\n\nRun tests with:\n\n```bash\nyarn test\n```\n\n## Notes\n- This package assumes your repository is configured with GitHub Actions and that you have a GitHub OIDC role configured in AWS.\n- The generated script uses the AWS SDK v3 for CloudFormation and posts comments using the GitHub REST API.\n"
   },
   "repository": {
     "type": "git",
@@ -3573,7 +3573,7 @@
         },
         "locationInModule": {
           "filename": "src/CdkDiffIamTemplate.ts",
-          "line": 10
+          "line": 12
         },
         "parameters": [
           {
@@ -3587,7 +3587,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/CdkDiffIamTemplate.ts",
-        "line": 9
+        "line": 11
       },
       "name": "CdkDiffIamTemplate",
       "symbolId": "src/CdkDiffIamTemplate:CdkDiffIamTemplate"
@@ -3606,6 +3606,36 @@
       },
       "name": "CdkDiffIamTemplateProps",
       "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 8
+          },
+          "name": "oidcRegion",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 7
+          },
+          "name": "oidcRoleArn",
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -3631,8 +3661,7 @@
             "filename": "src/CdkDiffIamTemplate.ts",
             "line": 5
           },
-          "name": "outputPath",
-          "optional": true,
+          "name": "roleName",
           "type": {
             "primitive": "string"
           }
@@ -3647,7 +3676,7 @@
             "filename": "src/CdkDiffIamTemplate.ts",
             "line": 6
           },
-          "name": "stackName",
+          "name": "outputPath",
           "optional": true,
           "type": {
             "primitive": "string"
@@ -3680,7 +3709,7 @@
             "filename": "src/CdkDiffStackWorkflow.ts",
             "line": 11
           },
-          "name": "cdkDiffRoleToAssumeArn",
+          "name": "changesetRoleToAssumeArn",
           "type": {
             "primitive": "string"
           }
@@ -3695,7 +3724,7 @@
             "filename": "src/CdkDiffStackWorkflow.ts",
             "line": 12
           },
-          "name": "cdkDiffRoleToAssumeRegion",
+          "name": "changesetRoleToAssumeRegion",
           "type": {
             "primitive": "string"
           }
@@ -3910,8 +3939,132 @@
         }
       ],
       "symbolId": "src/CdkDiffStackWorkflow:CdkDiffStackWorkflowProps"
+    },
+    "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplate": {
+      "assembly": "@jjrawlins/cdk-diff-pr-github-action",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplate",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "locationInModule": {
+          "filename": "src/CdkDriftIamTemplate.ts",
+          "line": 12
+        },
+        "parameters": [
+          {
+            "name": "props",
+            "type": {
+              "fqn": "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplateProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/CdkDriftIamTemplate.ts",
+        "line": 11
+      },
+      "name": "CdkDriftIamTemplate",
+      "symbolId": "src/CdkDriftIamTemplate:CdkDriftIamTemplate"
+    },
+    "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplateProps": {
+      "assembly": "@jjrawlins/cdk-diff-pr-github-action",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplateProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/CdkDriftIamTemplate.ts",
+        "line": 3
+      },
+      "name": "CdkDriftIamTemplateProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 8
+          },
+          "name": "oidcRegion",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 7
+          },
+          "name": "oidcRoleArn",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 4
+          },
+          "name": "project",
+          "type": {
+            "primitive": "any"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 5
+          },
+          "name": "roleName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 6
+          },
+          "name": "outputPath",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/CdkDriftIamTemplate:CdkDriftIamTemplateProps"
     }
   },
   "version": "0.0.0",
-  "fingerprint": "tHH4O3w5aknRRboRsohbwELbBny5Nck+ehKsoWl+2Rw="
+  "fingerprint": "jeIoS9wFV5gvSB5n6I47EQ8xc8cvuCuUbHfjjZ0ESFg="
 }

package/.yalc/@jjrawlins/cdk-diff-pr-github-action/.jsii

@@ -3548,7 +3548,7 @@
   },
   "name": "@jjrawlins/cdk-diff-pr-github-action",
   "readme": {
-    "markdown": "# cdk-diff-pr-github-action\n\nA small Projen-based helper library that wires a GitHub workflow to create a CloudFormation Change Set for a CDK stack on every pull request, then comments the formatted diff back on the PR. It also provides a ready‑to‑deploy IAM template you can use to grant the minimal permissions required for the workflow to create and inspect change sets.\n\nThis package exposes two constructs:\n\n- `CdkDiffStackWorkflow` — Generates one GitHub Actions workflow per stack that:\n  - Assumes your GitHub OIDC role\n  - Optionally chains into a separate CDK deploy role\n  - Runs `cdk deploy --no-execute` to create a change set\n  - Runs a generated script to render the change set as an HTML table and posts it to the PR and to the GitHub Step Summary\n  - Cleans up the change set\n\n- `CdkDiffIamTemplate` — Emits a CloudFormation template file (`cdk-diff-workflow-iam-template.yaml`) containing an example IAM role policy with the minimal permissions to create, describe, and delete CloudFormation change sets and read common CDK bootstrap resources. You can launch this in your account and then reference the created role.\n\n## Quick start\n\n1) Add the constructs to your Projen project (in `.projenrc.ts`).\n2) Synthesize with `npx projen`.\n3) Commit the generated files.\n4) Open a pull request — the workflow will create a change set and comment the diff.\n\n## Usage: CdkDiffStackWorkflow\n\n`CdkDiffStackWorkflow` renders a workflow per stack named `diff-<StackName>.yml` under `.github/workflows/`. It also generates a helper script at `.github/workflows/scripts/describe-cfn-changeset.ts` that formats the change set output and takes care of posting the PR comment and Step Summary.\n\nExample `.projenrc.ts`:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffStackWorkflow } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ... your usual settings ...\n  name: 'my-lib',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.85.0',\n  github: true,\n});\n\nnew CdkDiffStackWorkflow({\n  project,\n  // Stacks to diff on PRs\n  stacks: [\n    {\n      stackName: 'MyAppStack',\n      cdkDiffRoleToAssumeArn: 'arn:aws:iam::123456789012:role/cdk-diff-role',\n      cdkDiffRoleToAssumeRegion: 'us-east-1',\n      // Optional per‑stack OIDC override (if not using the defaults below)\n      // oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n      // oidcRegion: 'us-east-1',\n    },\n  ],\n  // Default OIDC role/region used by all stacks unless overridden per‑stack\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: Node version used in the workflow (default: '24.x')\n  // nodeVersion: '20.x',\n  // Optional: Yarn command to run CDK (default: 'cdk')\n  // cdkYarnCommand: 'cdk',\n  // Optional: Where to place the helper script\n  // scriptOutputPath: '.github/workflows/scripts/describe-cfn-changeset.ts',\n});\n\nproject.synth();\n```\n\n### Required properties\n- `project` (AwsCdkTypeScriptApp) — Your Projen project instance.\n- `stacks` (array) — One entry per CDK stack you want a diff for.\n- OIDC configuration: either\n  - Provide `oidcRoleArn` and `oidcRegion` at the top level, or\n  - Provide `oidcRoleArn` and `oidcRegion` on every stack item.\n\nIf neither the defaults nor all per‑stack values are supplied, the construct throws with a helpful error.\n\n### Stack item fields\n- `stackName` — The CDK stack name to create the change set for.\n- `cdkDiffRoleToAssumeArn` — The ARN of the role used to create the change set (role chaining after OIDC).\n- `cdkDiffRoleToAssumeRegion` — The region for that role.\n- `oidcRoleArn` (optional) — Per‑stack override for the OIDC role.\n- `oidcRegion` (optional) — Per‑stack override for the OIDC region.\n\n### What gets generated\n- `.github/workflows/diff-<StackName>.yml` — One workflow per stack, triggered on PR open/sync/reopen.\n- `.github/workflows/scripts/describe-cfn-changeset.ts` — A helper script that:\n  - Polls `DescribeChangeSet` until terminal\n  - Filters out ignorable logical IDs or resource types using environment variables `IGNORE_LOGICAL_IDS` and `IGNORE_RESOURCE_TYPES`\n  - Renders an HTML table with actions, logical IDs, types, replacements, and changed properties\n  - Prints the HTML, appends to the GitHub Step Summary, and (if `GITHUB_TOKEN` and `GITHUB_COMMENT_URL` are present) posts a PR comment\n\n### Environment variables used by the script\n- `STACK_NAME` (required) — Stack name to describe.\n- `CHANGE_SET_NAME` (default: same as `STACK_NAME`).\n- `AWS_REGION` — Region for CloudFormation API calls. The workflow sets this via the credentials action.\n- `GITHUB_TOKEN` (optional) — If set with `GITHUB_COMMENT_URL`, posts a PR comment.\n- `GITHUB_COMMENT_URL` (optional) — PR comments URL.\n- `GITHUB_STEP_SUMMARY` (optional) — When present, appends the HTML to the step summary file.\n- `IGNORE_LOGICAL_IDS` (optional) — Comma‑separated logical IDs to ignore (default includes `CDKMetadata`).\n- `IGNORE_RESOURCE_TYPES` (optional) — Comma‑separated resource types to ignore (e.g., `AWS::CDK::Metadata`).\n\n## Usage: CdkDiffIamTemplate\n\nAdd `CdkDiffIamTemplate` to your Projen project to emit an example IAM template you can deploy in your account:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ...\n});\n\nnew CdkDiffIamTemplate({ project });\n\nproject.synth();\n```\n\nThis will write `cdk-diff-workflow-iam-template.yaml` at the project root. The template defines:\n- A parameter `GitHubOIDCRoleArn` — pass the ARN of your existing GitHub OIDC role that will assume the change set role.\n- An IAM role `CdkChangesetRole` with minimal permissions for:\n  - CloudFormation Change Set operations\n  - Access to common CDK bootstrap S3 buckets and SSM parameters\n  - `iam:PassRole` to `cloudformation.amazonaws.com`\n- Outputs exporting the role name and ARN.\n\nYou can deploy the file via CloudFormation/StackSets and then use the created role ARN as the `cdkDiffRoleToAssumeArn` in your workflow configuration.\n\n## Testing\n\nThis repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:\n- Workflows are created per stack and contain all expected steps.\n- Only one script file is generated.\n- Per‑stack OIDC overrides are respected.\n- Helpful validation errors are thrown for missing OIDC settings.\n- The IAM template file contains the expected resources and outputs.\n\nRun tests with:\n\n```bash\nyarn test\n```\n\n## Notes\n- This package assumes your repository is configured with GitHub Actions and that you have a GitHub OIDC role configured in AWS.\n- The generated script uses the AWS SDK v3 for CloudFormation and posts comments using the GitHub REST API.\n"
+    "markdown": "# cdk-diff-pr-github-action\n\nA small Projen-based helper library that wires a GitHub workflow to create a CloudFormation Change Set for a CDK stack on every pull request, then comments the formatted diff back on the PR. It also provides a ready‑to‑deploy IAM template you can use to grant the minimal permissions required for the workflow to create and inspect change sets.\n\nThis package exposes two constructs:\n\n- `CdkDiffStackWorkflow` — Generates one GitHub Actions workflow per stack that:\n  - Assumes your GitHub OIDC role\n  - Optionally chains into a separate CDK deploy role\n  - Runs `cdk deploy --no-execute` to create a change set\n  - Runs a generated script to render the change set as an HTML table and posts it to the PR and to the GitHub Step Summary\n  - Cleans up the change set\n\n- `CdkDiffIamTemplate` — Emits a CloudFormation template file (`cdk-diff-workflow-iam-template.yaml`) containing an example IAM role policy with the minimal permissions to create, describe, and delete CloudFormation change sets and read common CDK bootstrap resources. You can launch this in your account and then reference the created role.\n\n## Quick start\n\n1) Add the constructs to your Projen project (in `.projenrc.ts`).\n2) Synthesize with `npx projen`.\n3) Commit the generated files.\n4) Open a pull request — the workflow will create a change set and comment the diff.\n\n## Usage: CdkDiffStackWorkflow\n\n`CdkDiffStackWorkflow` renders a workflow per stack named `diff-<StackName>.yml` under `.github/workflows/`. It also generates a helper script at `.github/workflows/scripts/describe-cfn-changeset.ts` that formats the change set output and takes care of posting the PR comment and Step Summary.\n\nExample `.projenrc.ts`:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffStackWorkflow } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ... your usual settings ...\n  name: 'my-lib',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.85.0',\n  github: true,\n});\n\nnew CdkDiffStackWorkflow({\n  project,\n  // Stacks to diff on PRs\n  stacks: [\n    {\n      stackName: 'MyAppStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::123456789012:role/cdk-diff-role',\n      changesetRoleToAssumeRegion: 'us-east-1',\n      // Optional per‑stack OIDC override (if not using the defaults below)\n      // oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n      // oidcRegion: 'us-east-1',\n    },\n  ],\n  // Default OIDC role/region used by all stacks unless overridden per‑stack\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: Node version used in the workflow (default: '24.x')\n  // nodeVersion: '20.x',\n  // Optional: Yarn command to run CDK (default: 'cdk')\n  // cdkYarnCommand: 'cdk',\n  // Optional: Where to place the helper script\n  // scriptOutputPath: '.github/workflows/scripts/describe-cfn-changeset.ts',\n});\n\nproject.synth();\n```\n\n### Required properties\n- `project` (AwsCdkTypeScriptApp) — Your Projen project instance.\n- `stacks` (array) — One entry per CDK stack you want a diff for.\n- OIDC configuration: either\n  - Provide `oidcRoleArn` and `oidcRegion` at the top level, or\n  - Provide `oidcRoleArn` and `oidcRegion` on every stack item.\n\nIf neither the defaults nor all per‑stack values are supplied, the construct throws with a helpful error.\n\n### Stack item fields\n- `stackName` — The CDK stack name to create the change set for.\n- `changesetRoleToAssumeArn` — The ARN of the role used to create the change set (role chaining after OIDC).\n- `changesetRoleToAssumeRegion` — The region for that role.\n- `oidcRoleArn` (optional) — Per‑stack override for the OIDC role.\n- `oidcRegion` (optional) — Per‑stack override for the OIDC region.\n\n### What gets generated\n- `.github/workflows/diff-<StackName>.yml` — One workflow per stack, triggered on PR open/sync/reopen.\n- `.github/workflows/scripts/describe-cfn-changeset.ts` — A helper script that:\n  - Polls `DescribeChangeSet` until terminal\n  - Filters out ignorable logical IDs or resource types using environment variables `IGNORE_LOGICAL_IDS` and `IGNORE_RESOURCE_TYPES`\n  - Renders an HTML table with actions, logical IDs, types, replacements, and changed properties\n  - Prints the HTML, appends to the GitHub Step Summary, and (if `GITHUB_TOKEN` and `GITHUB_COMMENT_URL` are present) posts a PR comment\n\n### Environment variables used by the script\n- `STACK_NAME` (required) — Stack name to describe.\n- `CHANGE_SET_NAME` (default: same as `STACK_NAME`).\n- `AWS_REGION` — Region for CloudFormation API calls. The workflow sets this via the credentials action.\n- `GITHUB_TOKEN` (optional) — If set with `GITHUB_COMMENT_URL`, posts a PR comment.\n- `GITHUB_COMMENT_URL` (optional) — PR comments URL.\n- `GITHUB_STEP_SUMMARY` (optional) — When present, appends the HTML to the step summary file.\n- `IGNORE_LOGICAL_IDS` (optional) — Comma‑separated logical IDs to ignore (default includes `CDKMetadata`).\n- `IGNORE_RESOURCE_TYPES` (optional) — Comma‑separated resource types to ignore (e.g., `AWS::CDK::Metadata`).\n\n## Usage: CdkDiffIamTemplate\n\nAdd `CdkDiffIamTemplate` to your Projen project to emit an example IAM template you can deploy in your account:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ...\n});\n\nnew CdkDiffIamTemplate({ project });\n\nproject.synth();\n```\n\nThis will write `cdk-diff-workflow-iam-template.yaml` at the project root. The template defines:\n- A parameter `GitHubOIDCRoleArn` — pass the ARN of your existing GitHub OIDC role that will assume the change set role.\n- An IAM role `CdkChangesetRole` with minimal permissions for:\n  - CloudFormation Change Set operations\n  - Access to common CDK bootstrap S3 buckets and SSM parameters\n  - `iam:PassRole` to `cloudformation.amazonaws.com`\n- Outputs exporting the role name and ARN.\n\nYou can deploy the file via CloudFormation/StackSets and then use the created role ARN as the `changesetRoleToAssumeArn` in your workflow configuration.\n\n## Testing\n\nThis repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:\n- Workflows are created per stack and contain all expected steps.\n- Only one script file is generated.\n- Per‑stack OIDC overrides are respected.\n- Helpful validation errors are thrown for missing OIDC settings.\n- The IAM template file contains the expected resources and outputs.\n\nRun tests with:\n\n```bash\nyarn test\n```\n\n## Notes\n- This package assumes your repository is configured with GitHub Actions and that you have a GitHub OIDC role configured in AWS.\n- The generated script uses the AWS SDK v3 for CloudFormation and posts comments using the GitHub REST API.\n"
   },
   "repository": {
     "type": "git",
@@ -3573,7 +3573,7 @@
         },
         "locationInModule": {
           "filename": "src/CdkDiffIamTemplate.ts",
-          "line": 10
+          "line": 12
         },
         "parameters": [
           {
@@ -3587,7 +3587,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/CdkDiffIamTemplate.ts",
-        "line": 9
+        "line": 11
       },
       "name": "CdkDiffIamTemplate",
       "symbolId": "src/CdkDiffIamTemplate:CdkDiffIamTemplate"
@@ -3606,6 +3606,36 @@
       },
       "name": "CdkDiffIamTemplateProps",
       "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 8
+          },
+          "name": "oidcRegion",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 7
+          },
+          "name": "oidcRoleArn",
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -3631,8 +3661,7 @@
             "filename": "src/CdkDiffIamTemplate.ts",
             "line": 5
           },
-          "name": "outputPath",
-          "optional": true,
+          "name": "roleName",
           "type": {
             "primitive": "string"
           }
@@ -3647,7 +3676,7 @@
             "filename": "src/CdkDiffIamTemplate.ts",
             "line": 6
           },
-          "name": "stackName",
+          "name": "outputPath",
           "optional": true,
           "type": {
             "primitive": "string"
@@ -3680,7 +3709,7 @@
             "filename": "src/CdkDiffStackWorkflow.ts",
             "line": 11
           },
-          "name": "cdkDiffRoleToAssumeArn",
+          "name": "changesetRoleToAssumeArn",
           "type": {
             "primitive": "string"
           }
@@ -3695,7 +3724,7 @@
             "filename": "src/CdkDiffStackWorkflow.ts",
             "line": 12
           },
-          "name": "cdkDiffRoleToAssumeRegion",
+          "name": "changesetRoleToAssumeRegion",
           "type": {
             "primitive": "string"
           }
@@ -3910,8 +3939,132 @@
         }
       ],
       "symbolId": "src/CdkDiffStackWorkflow:CdkDiffStackWorkflowProps"
+    },
+    "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplate": {
+      "assembly": "@jjrawlins/cdk-diff-pr-github-action",
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplate",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "locationInModule": {
+          "filename": "src/CdkDriftIamTemplate.ts",
+          "line": 12
+        },
+        "parameters": [
+          {
+            "name": "props",
+            "type": {
+              "fqn": "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplateProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/CdkDriftIamTemplate.ts",
+        "line": 11
+      },
+      "name": "CdkDriftIamTemplate",
+      "symbolId": "src/CdkDriftIamTemplate:CdkDriftIamTemplate"
+    },
+    "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplateProps": {
+      "assembly": "@jjrawlins/cdk-diff-pr-github-action",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "@jjrawlins/cdk-diff-pr-github-action.CdkDriftIamTemplateProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/CdkDriftIamTemplate.ts",
+        "line": 3
+      },
+      "name": "CdkDriftIamTemplateProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 8
+          },
+          "name": "oidcRegion",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 7
+          },
+          "name": "oidcRoleArn",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 4
+          },
+          "name": "project",
+          "type": {
+            "primitive": "any"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 5
+          },
+          "name": "roleName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftIamTemplate.ts",
+            "line": 6
+          },
+          "name": "outputPath",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ],
+      "symbolId": "src/CdkDriftIamTemplate:CdkDriftIamTemplateProps"
     }
   },
   "version": "0.0.0",
-  "fingerprint": "tHH4O3w5aknRRboRsohbwELbBny5Nck+ehKsoWl+2Rw="
-}
+  "fingerprint": "adohpOK53C4dMRZxwaE9ciWaUP4MnX0Z+VFGeRuc+3o="
+}