@jjrawlins/cdk-diff-pr-github-action 1.8.0 → 1.9.0

package/.jsii

@@ -3507,7 +3507,7 @@
   },
   "name": "@jjrawlins/cdk-diff-pr-github-action",
   "readme": {
-    "markdown": "# cdk-diff-pr-github-action\n\nA [Projen](https://projen.io/) construct library that surfaces **CloudFormation change set diffs and drift status directly on your pull requests** so reviewers can see exactly what will change before merging.\n\n## Why this exists\n\n`cdk diff` output disappears into CI logs that nobody reads. Meanwhile, a single property change on an RDS instance or EC2 \"pet\" server can trigger a **resource replacement** — destroying the database or instance and recreating it from scratch. If that replacement slips through code review unnoticed, the result is data loss and downtime.\n\nThis construct was built to make those dangerous changes impossible to miss:\n\n- **Replacement column front and center** — Every change set row shows whether CloudFormation will modify the resource in place or **replace** it, with before/after property values so reviewers can understand *why*.\n- **Comment appears on the PR itself** — No digging through workflow logs. The diff table is posted (and updated in place) as a PR comment and in the GitHub Step Summary.\n- **Drift banner** — If the stack has drifted from its template, a warning banner is prepended to the comment so reviewers know the baseline is already out of sync.\n\nIf you have ever lost an EC2 instance, an RDS database, or an ElastiCache cluster to an unexpected CloudFormation replacement, this tool is for you.\n\n---\n\nA library that provides GitHub workflows and IAM templates for:\n- Creating CloudFormation Change Sets for your CDK stacks on pull requests and commenting a formatted diff back on the PR.\n- Detecting CloudFormation drift on a schedule or manual trigger and producing a consolidated summary (optionally creating an issue).\n- Deploying IAM roles across AWS Organizations using StackSets.\n\nIt also provides ready-to-deploy IAM templates with the minimal permissions required for each workflow.\n\n**Works with or without Projen** -- The StackSet generator can be used standalone in any Node.js project.\n\nThis package exposes five constructs:\n\n- `CdkDiffStackWorkflow` — Generates one GitHub Actions workflow per stack to create a change set and render the diff back to the PR and Step Summary.\n- `CdkDiffIamTemplate` — Emits a CloudFormation template file with minimal permissions for the Change Set workflow.\n- `CdkDriftDetectionWorkflow` — Generates a GitHub Actions workflow to detect CloudFormation drift per stack, upload machine‑readable results, and aggregate a summary.\n- `CdkDriftIamTemplate` — Emits a CloudFormation template file with minimal permissions for the Drift Detection workflow.\n- `CdkDiffIamTemplateStackSet` — Creates a CloudFormation StackSet template for org-wide deployment of GitHub OIDC and IAM roles (Projen integration).\n- `CdkDiffIamTemplateStackSetGenerator` — Pure generator class for StackSet templates (no Projen dependency).\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 or run the drift detection workflow.\n\n## End-to-end example\n\nA realistic setup for a CDK Pipelines project with multiple stages and accounts. This generates one diff workflow per stack, a shared IAM template, and a scheduled drift detection workflow.\n\n```ts\n// .projenrc.ts\nimport { awscdk } from 'projen';\nimport {\n  CdkDiffStackWorkflow,\n  CdkDiffIamTemplate,\n  CdkDriftDetectionWorkflow,\n} from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkTypeScriptApp({\n  name: 'my-data-platform',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.170.0',\n  github: true,\n});\n\n// --- Change Set Diff Workflows (one per stack) ---\n// stackName is the CDK construct path used with `cdk deploy <target>`.\n// For CDK Pipelines, this is typically: pipeline/Stage/Stack\n// The construct automatically resolves the real CloudFormation stack name\n// from cdk.out at runtime (e.g., \"my-stage-dev-my-stack\").\n\nnew CdkDiffStackWorkflow({\n  project,\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'my-pipeline/dev/DatabaseStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::111111111111:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n    },\n    {\n      stackName: 'my-pipeline/dev/ComputeStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::111111111111:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n    },\n    {\n      // Cross-account: prod stacks can use a different OIDC role and region\n      stackName: 'my-pipeline/prod/DatabaseStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::222222222222:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n      oidcRoleArn: 'arn:aws:iam::222222222222:role/GitHubOIDCRole',\n      oidcRegion: 'us-east-1',\n    },\n  ],\n});\n\n// --- IAM Template (deploy once per account) ---\nnew CdkDiffIamTemplate({\n  project,\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['my-data-platform'],\n    branches: ['main'],\n  },\n});\n\n// --- Drift Detection (scheduled + manual) ---\nnew CdkDriftDetectionWorkflow({\n  project,\n  schedule: '0 6 * * 1', // Every Monday at 6 AM UTC\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'dev-DatabaseStack',\n      driftDetectionRoleToAssumeArn: 'arn:aws:iam::111111111111:role/CdkDriftRole',\n      driftDetectionRoleToAssumeRegion: 'us-east-1',\n    },\n  ],\n});\n\nproject.synth();\n```\n\nAfter `npx projen`, this generates:\n- `.github/workflows/diff-my-pipeline-dev-databasestack.yml`\n- `.github/workflows/diff-my-pipeline-dev-computestack.yml`\n- `.github/workflows/diff-my-pipeline-prod-databasestack.yml`\n- `.github/workflows/scripts/describe-cfn-changeset.ts`\n- `.github/workflows/drift-detection.yml`\n- `.github/workflows/scripts/detect-drift.ts`\n- `cdk-diff-workflow-iam-template.yaml`\n\nWhen a pull request is opened, each diff workflow runs automatically and posts a comment like this:\n\n| Action | ID | Type | Replacement | Details |\n|--------|-----|------|-------------|---------|\n| 🔵 Modify | MyDatabase | AWS::RDS::DBInstance | **True** | 🔵 **DBInstanceClass**: `db.t3.medium` -> `db.t3.large` |\n| 🔵 Modify | MyFunction | AWS::Lambda::Function | False | 🔵 **Runtime**: `nodejs18.x` -> `nodejs20.x` |\n\nThe **Replacement: True** on the RDS instance is exactly the kind of change this tool is designed to catch before it reaches production.\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  workflowName: 'my-lib',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.85.0',\n  github: true,\n});\n\nnew CdkDiffStackWorkflow({\n  project,\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: '24.x',\n  // Optional: Yarn command to run CDK (default: 'cdk')\n  // cdkYarnCommand: 'cdk',\n  // Optional: Where to place the helper script (default: '.github/workflows/scripts/describe-cfn-changeset.ts')\n  // scriptOutputPath: '.github/workflows/scripts/describe-cfn-changeset.ts',\n});\n\nproject.synth();\n```\n\n### CdkDiffStackWorkflow props\n- `project` (required) — Your Projen project instance.\n- `stacks` (required) — Array of stack entries.\n- `oidcRoleArn` (required unless provided per‑stack) — Default OIDC role ARN.\n- `oidcRegion` (required unless provided per‑stack) — Default OIDC region.\n- `nodeVersion` (optional, default `'24.x'`) — Node.js version for the workflow runner.\n- `cdkYarnCommand` (optional, default `'cdk'`) — Yarn script/command to invoke CDK.\n- `scriptOutputPath` (optional, default `'.github/workflows/scripts/describe-cfn-changeset.ts'`) — Where to write the helper script.\n- `workingDirectory` (optional) — Subdirectory where the CDK app lives (e.g., `'infra'`). Sets `defaults.run.working-directory` on all jobs so `install`, `synth`, and `deploy` steps run in that directory. The describe-changeset script path is automatically prefixed with `$GITHUB_WORKSPACE/` and `NODE_PATH` is set to resolve modules from the working directory.\n\nIf neither top‑level OIDC defaults nor all per‑stack values are supplied, the construct throws a helpful error.\n\n### Stack item fields\n- `stackName` (required) — The CDK stack name to create the change set for.\n- `changesetRoleToAssumeArn` (required) — The ARN of the role used to create the change set (role chaining after OIDC).\n- `changesetRoleToAssumeRegion` (required) — 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  - **Checks cached drift status** via `DescribeStacks` — if the stack has drifted, a warning banner with drifted resource details is prepended to the output (non-fatal; degrades gracefully if IAM permissions are missing)\n  - Prints the HTML and appends to the GitHub Step Summary\n  - **Upserts the PR comment** — uses an HTML marker (`<!-- cdk-diff:stack:STACK_NAME -->`) to find and update an existing comment instead of creating duplicates on every push\n\n### Change Set Output Format\n\nThe change set script uses the CloudFormation `IncludePropertyValues` API feature to show **actual before/after values** for changed properties, not just property names.\n\n**Example PR comment:**\n\n> **Warning: Stack has drifted (2 resources out of sync)**\n>\n> Last drift check: 2025-01-15T10:30:00.000Z\n>\n> <details><summary>View drifted resources</summary>\n>\n> | Resource | Type | Drift Status |\n> |----------|------|-------------|\n> | MySecurityGroup | AWS::EC2::SecurityGroup | MODIFIED |\n> | OldBucket | AWS::S3::Bucket | DELETED |\n> </details>\n\n| Action | ID | Type | Replacement | Details |\n|--------|-----|------|-------------|---------|\n| 🔵 Modify | MyDatabase | AWS::RDS::DBInstance | **True** | 🔵 **DBInstanceClass**: `db.t3.medium` -> `db.t3.large` |\n| 🔵 Modify | MyLambdaFunction | AWS::Lambda::Function | False | 🔵 **Runtime**: `nodejs18.x` -> `nodejs20.x` |\n| 🟢 Add | NewSecurityGroup | AWS::EC2::SecurityGroup | - | |\n| 🔴 Remove | OldRole | AWS::IAM::Role | - | |\n\n**Features:**\n- **Replacement column** highlights when CloudFormation will **destroy and recreate** a resource — critical for stateful resources like databases, EC2 instances, and file systems\n- **Drift banner** — if the stack has drifted, a warning with drifted resource details appears above the change set table so reviewers know the baseline state\n- **Comment upsert** — each stack's comment is updated in place on subsequent pushes instead of creating duplicates; uses an HTML marker for reliable find-and-replace\n- **Color-coded indicators**: 🟢 Added, 🔵 Modified, 🔴 Removed\n- **Inline values for small changes**: Shows `before -> after` directly in the table\n- **Collapsible details for large values**: IAM policies, tags, and other large JSON values are wrapped in expandable `<details>` elements to keep the table readable\n- **All attribute types supported**: Properties, Tags, Metadata, etc.\n- **HTML-escaped values**: Prevents XSS from property values\n\n### Environment variables used by the change set 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(s).\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\nEmit an IAM template you can deploy in your account for the Change Set workflow. Supports two modes:\n\n1. **External OIDC Role** — Reference an existing GitHub OIDC role (original behavior)\n2. **Self-Contained** — Create the GitHub OIDC provider and role within the same template (new)\n\n### Option 1: Using an Existing OIDC Role (External)\n\nUse this when you already have a GitHub OIDC provider and role set up in your account.\n\n#### With Projen\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({\n  project,\n  roleName: 'cdk-diff-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: custom output path (default: 'cdk-diff-workflow-iam-template.yaml')\n  // outputPath: 'infra/cdk-diff-iam.yaml',\n});\n\nproject.synth();\n```\n\n#### Without Projen (Standalone Generator)\n\n```ts\nimport { CdkDiffIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\nconst template = CdkDiffIamTemplateGenerator.generateTemplate({\n  roleName: 'cdk-diff-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n});\n\nfs.writeFileSync('cdk-diff-iam-template.yaml', template);\n```\n\n### Option 2: Self-Contained Template (Create OIDC Role)\n\nUse this when you want a single template that creates everything needed — the GitHub OIDC provider, OIDC role, and changeset role. This simplifies deployment and pairs well with the `CdkDiffStackWorkflow`.\n\n#### With Projen\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({\n  project,\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  oidcRoleName: 'GitHubOIDCRole',  // Optional, default: 'GitHubOIDCRole'\n  githubOidc: {\n    owner: 'my-org',                          // GitHub org or username\n    repositories: ['infra-repo', 'app-repo'], // Repos allowed to assume roles\n    branches: ['main', 'release/*'],          // Branch patterns (default: ['*'])\n  },\n  // Optional: Skip OIDC provider creation if it already exists\n  // skipOidcProviderCreation: true,\n});\n\nproject.synth();\n```\n\n#### Without Projen (Standalone Generator)\n\n```ts\nimport { CdkDiffIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\nconst template = CdkDiffIamTemplateGenerator.generateTemplate({\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  oidcRoleName: 'GitHubOIDCRole',\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['infra-repo'],\n    branches: ['main'],\n  },\n});\n\nfs.writeFileSync('cdk-diff-iam-template.yaml', template);\n```\n\n#### With Existing OIDC Provider (Skip Creation)\n\nIf your account already has a GitHub OIDC provider but you want the template to create the roles:\n\n```ts\nnew CdkDiffIamTemplate({\n  project,\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  skipOidcProviderCreation: true,  // Account already has OIDC provider\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['*'],  // All repos in org\n  },\n});\n```\n\n### Deploy Task\n\nA Projen task is added for easy deployment:\n\n```bash\nnpx projen deploy-cdkdiff-iam-template -- --parameter-overrides GitHubOIDCRoleArn=... # plus any extra AWS CLI args\n```\n\n### CdkDiffIamTemplate Props\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `roleName` | `string` | Name for the changeset IAM role (required) |\n| `oidcRoleArn` | `string?` | ARN of existing GitHub OIDC role. Required when `createOidcRole` is false. |\n| `oidcRegion` | `string?` | Region for OIDC trust condition. Required when `createOidcRole` is false. |\n| `createOidcRole` | `boolean?` | Create OIDC role within template (default: false) |\n| `oidcRoleName` | `string?` | Name of OIDC role to create (default: 'GitHubOIDCRole') |\n| `githubOidc` | `GitHubOidcConfig?` | GitHub OIDC config. Required when `createOidcRole` is true. |\n| `skipOidcProviderCreation` | `boolean?` | Skip OIDC provider if it exists (default: false) |\n| `outputPath` | `string?` | Template output path (default: 'cdk-diff-workflow-iam-template.yaml') |\n\n### What the Template Creates\n\n**External OIDC Role mode:**\n- Parameter `GitHubOIDCRoleArn` — ARN of your existing GitHub OIDC role\n- IAM role `CdkChangesetRole` with minimal permissions for change set operations\n- Outputs: `CdkChangesetRoleArn`, `CdkChangesetRoleName`\n\n**Self-Contained mode (`createOidcRole: true`):**\n- GitHub OIDC Provider (unless `skipOidcProviderCreation: true`)\n- IAM role `GitHubOIDCRole` with trust policy for GitHub Actions\n- IAM role `CdkChangesetRole` with minimal permissions (trusts the OIDC role)\n- Outputs: `GitHubOIDCProviderArn`, `GitHubOIDCRoleArn`, `GitHubOIDCRoleName`, `CdkChangesetRoleArn`, `CdkChangesetRoleName`\n\n**Changeset Role Permissions:**\n- CloudFormation Change Set operations\n- Access to CDK bootstrap S3 buckets and SSM parameters\n- `iam:PassRole` to `cloudformation.amazonaws.com`\n\nUse the created changeset role ARN as `changesetRoleToAssumeArn` in `CdkDiffStackWorkflow`.\n\n---\n\n## Usage: CdkDriftDetectionWorkflow\n\n`CdkDriftDetectionWorkflow` creates a single workflow file (default `drift-detection.yml`) that can run on a schedule and via manual dispatch. It generates a helper script at `.github/workflows/scripts/detect-drift.ts` (by default) that uses AWS SDK v3 to run drift detection, write optional machine‑readable JSON, and print an HTML report for the Step Summary.\n\nExample `.projenrc.ts`:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDriftDetectionWorkflow } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({ github: true, /* ... */ });\n\nnew CdkDriftDetectionWorkflow({\n  project,\n  workflowName: 'Drift Detection',            // optional; file name derived as 'drift-detection.yml'\n  schedule: '0 1 * * *',                      // optional cron\n  createIssues: true,                         // default true; create/update issue when drift detected on schedule\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: Node version (default '24.x')\n  // nodeVersion: '24.x',\n  // Optional: Where to place the helper script (default '.github/workflows/scripts/detect-drift.ts')\n  // scriptOutputPath: '.github/workflows/scripts/detect-drift.ts',\n  stacks: [\n    {\n      stackName: 'MyAppStack-Prod',\n      driftDetectionRoleToAssumeArn: 'arn:aws:iam::123456789012:role/cdk-drift-role',\n      driftDetectionRoleToAssumeRegion: 'us-east-1',\n      // failOnDrift: true, // optional (default true)\n    },\n  ],\n});\n\nproject.synth();\n```\n\n### CdkDriftDetectionWorkflow props\n- `project` (required) — Your Projen project instance.\n- `stacks` (required) — Array of stacks to check.\n- `oidcRoleArn` (required) — Default OIDC role ARN used before chaining into per‑stack drift roles.\n- `oidcRegion` (required) — Default OIDC region.\n- `workflowName` (optional, default `'drift-detection'`) — Human‑friendly workflow name; the file name is derived in kebab‑case.\n- `schedule` (optional) — Cron expression for automatic runs.\n- `createIssues` (optional, default `true`) — When true, scheduled runs will create/update a GitHub issue if drift is detected.\n- `nodeVersion` (optional, default `'24.x'`) — Node.js version for the runner.\n- `scriptOutputPath` (optional, default `'.github/workflows/scripts/detect-drift.ts'`) — Where to write the helper script.\n- `workingDirectory` (optional) — Subdirectory where the CDK app lives (e.g., `'infra'`). Sets `defaults.run.working-directory` on all jobs. Artifact upload and issue-script paths are automatically prefixed.\n\n### Per‑stack fields\n- `stackName` (required) — The full CloudFormation stack name.\n- `driftDetectionRoleToAssumeArn` (required) — Role to assume (after OIDC) for making drift API calls.\n- `driftDetectionRoleToAssumeRegion` (required) — Region for that role and API calls.\n- `failOnDrift` (optional, default `true`) — Intended to fail the detection step on drift. The provided script exits with non‑zero when drift is found; the job continues to allow artifact upload and issue creation.\n\n### What gets generated\n- `.github/workflows/<kebab(workflowName)>.yml` — A workflow with one job per stack plus a final summary job.\n- `.github/workflows/scripts/detect-drift.ts` — Helper script that:\n  - Starts drift detection and polls until completion\n  - Lists non‑`IN_SYNC` resources and builds an HTML report\n  - Writes optional JSON to `DRIFT_DETECTION_OUTPUT` when set\n  - Prints to stdout and appends to the GitHub Step Summary when available\n\n### Artifacts and summary\n- Each stack job uploads `drift-results-<stack>.json` (if produced).\n- A final `Drift Detection Summary` job downloads all artifacts and prints a consolidated summary.\n\n### Manual dispatch\n- The workflow exposes an input named `stack` with choices including each configured stack and an `all` option.\n- Choose a specific stack to run drift detection for that stack only, or select `all` (or leave the input empty) to run all stacks.\n\nNote: The default workflow does not post PR comments for drift. It can create/update an Issue on scheduled runs when `createIssues` is `true`.\n\n### Post-notification steps (e.g., Slack)\n\nYou can add your own GitHub Action steps to run after the drift detection step for each stack using `postGitHubSteps`.\nProvide your own Slack payload/markdown (this library no longer generates a payload step for you).\n\nOption A: slackapi/slack-github-action (Incoming Webhook, official syntax)\n\n```ts\nnew CdkDriftDetectionWorkflow({\n  project,\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  stacks: [/* ... */],\n  postGitHubSteps: ({ stack }) => {\n    // Build a descriptive name per stack\n    const name = `Notify Slack (${stack} post-drift)`;\n    const step = {\n      name,\n      uses: 'slackapi/slack-github-action@v2.1.1',\n      // by default, post steps run only when drift is detected; you can override `if`\n      if: \"always() && steps.drift.outcome == 'failure'\",\n      // Use official inputs: webhook + webhook-type, and a YAML payload with blocks\n      with: {\n        webhook: '${{ secrets.CDK_NOTIFICATIONS_SLACK_WEBHOOK }}',\n        'webhook-type': 'incoming-webhook',\n        payload: [\n          'text: \"** ${{ env.STACK_NAME }} ** has drifted!\"',\n          'blocks:',\n          '  - type: \"section\"',\n          '    text:',\n          '      type: \"mrkdwn\"',\n          '      text: \"*Stack:* ${{ env.STACK_NAME }} (region ${{ env.AWS_REGION }}) has drifted:exclamation:\"',\n          '  - type: \"section\"',\n          '    fields:',\n          '      - type: \"mrkdwn\"',\n          '        text: \"*Stack ARN*\\\\n${{ steps.drift.outputs.stack-arn }}\"',\n          '      - type: \"mrkdwn\"',\n          '        text: \"*Issue*\\\\n<${{ github.server_url }}/${{ github.repository }}/issues/${{ steps.issue.outputs.result }}|#${{ steps.issue.outputs.result }}>\"',\n        ].join('\\n'),\n      },\n    };\n    return [step];\n  },\n});\n```\n\nNote: The Issue link requires `createIssues: true` (default) so that the `Create Issue on Drift` step runs before this Slack step and exposes `steps.issue.outputs.result`. This library orders the steps accordingly.\n\nDetails:\n- `postGitHubSteps` can be:\n  - an array of step objects, or\n  - a factory function `({ stack }) => step | step[]`.\n- Each step you provide is inserted after the results are uploaded.\n- Default condition: if you do not set `if` on your step, it will default to `always() && steps.drift.outcome == 'failure'`.\n- Available context/env you can use:\n  - `${{ env.STACK_NAME }}`, `${{ env.DRIFT_DETECTION_OUTPUT }}`\n  - `${{ steps.drift.outcome }}` — success/failure of the detect step\n  - `${{ steps.drift.outputs.stack-arn }}` — Stack ARN resolved at runtime\n  - `${{ steps.issue.outputs.result }}` — Issue number if the workflow created/found one (empty when not applicable)\n```\n\n## Usage: CdkDriftIamTemplate\n\nEmit an example IAM template you can deploy in your account for the Drift Detection workflow.\n\n### With Projen\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDriftIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ...\n});\n\nnew CdkDriftIamTemplate({\n  project,\n  roleName: 'cdk-drift-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: custom output path (default: 'cdk-drift-workflow-iam-template.yaml')\n  // outputPath: 'infra/cdk-drift-iam.yaml',\n});\n\nproject.synth();\n```\n\nA Projen task is also added:\n\n```bash\nnpx projen deploy-cdkdrift-iam-template -- --parameter-overrides GitHubOIDCRoleArn=... # plus any extra AWS CLI args\n```\n\n### Without Projen (Standalone Generator)\n\n```ts\nimport { CdkDriftIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\nconst template = CdkDriftIamTemplateGenerator.generateTemplate({\n  roleName: 'cdk-drift-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n});\n\nfs.writeFileSync('cdk-drift-iam-template.yaml', template);\n\n// Get the deploy command\nconst deployCmd = CdkDriftIamTemplateGenerator.generateDeployCommand('cdk-drift-iam-template.yaml');\nconsole.log('Deploy with:', deployCmd);\n```\n\n### What the template defines\n\n- Parameter `GitHubOIDCRoleArn` with a default from `oidcRoleArn` — the ARN of your existing GitHub OIDC role allowed to assume this drift role.\n- IAM role `CdkDriftRole` with minimal permissions for CloudFormation drift detection operations.\n- Outputs exporting the role name and ARN.\n\n---\n\n## Usage: CdkDiffIamTemplateStackSet (Org-Wide Deployment)\n\n`CdkDiffIamTemplateStackSet` creates a CloudFormation StackSet template for deploying GitHub OIDC provider, OIDC role, and CDK diff/drift IAM roles across an entire AWS Organization. This is the recommended approach for organizations that want to enable CDK diff/drift workflows across multiple accounts.\n\n### Architecture\n\nEach account in your organization gets:\n- **GitHub OIDC Provider** — Authenticates GitHub Actions workflows\n- **GitHubOIDCRole** — Trusts the OIDC provider with repo/branch restrictions\n- **CdkChangesetRole** — For PR change set previews (trusts GitHubOIDCRole)\n- **CdkDriftRole** — For drift detection (trusts GitHubOIDCRole)\n\nThis is a self-contained deployment with **no role chaining required**.\n\n### With Projen\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffIamTemplateStackSet } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({ /* ... */ });\n\nnew CdkDiffIamTemplateStackSet({\n  project,\n  githubOidc: {\n    owner: 'my-org',                          // GitHub org or username\n    repositories: ['infra-repo', 'app-repo'], // Repos allowed to assume roles\n    branches: ['main', 'release/*'],          // Branch patterns (default: ['*'])\n  },\n  targetOrganizationalUnitIds: ['ou-xxxx-xxxxxxxx'], // Target OUs\n  regions: ['us-east-1', 'eu-west-1'],               // Target regions\n  // Optional settings:\n  // oidcRoleName: 'GitHubOIDCRole',       // default\n  // changesetRoleName: 'CdkChangesetRole', // default\n  // driftRoleName: 'CdkDriftRole',         // default\n  // roleSelection: StackSetRoleSelection.BOTH, // BOTH, CHANGESET_ONLY, or DRIFT_ONLY\n  // delegatedAdmin: true,                  // Use --call-as DELEGATED_ADMIN (default: true)\n});\n\nproject.synth();\n```\n\nThis creates:\n- `cdk-diff-workflow-stackset-template.yaml` — CloudFormation template\n- Projen tasks for StackSet management\n\n**Projen tasks:**\n```bash\nnpx projen stackset-create          # Create the StackSet\nnpx projen stackset-update          # Update the StackSet template\nnpx projen stackset-deploy-instances # Deploy to target OUs/regions\nnpx projen stackset-delete-instances # Remove stack instances\nnpx projen stackset-delete          # Delete the StackSet\nnpx projen stackset-describe        # Show StackSet status\nnpx projen stackset-list-instances  # List all instances\n```\n\n### Without Projen (Standalone Generator)\n\nFor non-Projen projects, use `CdkDiffIamTemplateStackSetGenerator` directly:\n\n```ts\nimport {\n  CdkDiffIamTemplateStackSetGenerator\n} from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\n// Generate the CloudFormation template\nconst template = CdkDiffIamTemplateStackSetGenerator.generateTemplate({\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['infra-repo'],\n    branches: ['main'],\n  },\n});\n\n// Write to file\nfs.writeFileSync('stackset-template.yaml', template);\n\n// Get AWS CLI commands for StackSet operations\nconst commands = CdkDiffIamTemplateStackSetGenerator.generateCommands({\n  stackSetName: 'cdk-diff-workflow-iam-stackset',\n  templatePath: 'stackset-template.yaml',\n  targetOrganizationalUnitIds: ['ou-xxxx-xxxxxxxx'],\n  regions: ['us-east-1'],\n});\n\nconsole.log('Create StackSet:', commands['stackset-create']);\nconsole.log('Deploy instances:', commands['stackset-deploy-instances']);\n```\n\n### GitHub Actions Workflow (Simplified)\n\nWith per-account OIDC, your workflow is simplified — no role chaining needed:\n\n```yaml\njobs:\n  diff:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: aws-actions/configure-aws-credentials@v4\n        with:\n          role-to-assume: arn:aws:iam::${{ env.ACCOUNT_ID }}:role/GitHubOIDCRole\n          aws-region: us-east-1\n\n      - name: Assume Changeset Role\n        run: |\n          CREDS=$(aws sts assume-role \\\n            --role-arn arn:aws:iam::${{ env.ACCOUNT_ID }}:role/CdkChangesetRole \\\n            --role-session-name changeset-session)\n          # Export credentials...\n```\n\n### GitHubOidcConfig options\n\n| Property | Description |\n|----------|-------------|\n| `owner` | GitHub organization or username (required) |\n| `repositories` | Array of repo names, or `['*']` for all repos (required) |\n| `branches` | Array of branch patterns (default: `['*']`) |\n| `additionalClaims` | Extra OIDC claims like `['pull_request', 'environment:production']` |\n\n---\n\n## Testing\n\nThis repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:\n- Diff workflows are created per stack and contain all expected steps.\n- Drift detection workflow produces one job per stack and a summary job.\n- Only one helper script file is generated per workflow type.\n- Per‑stack OIDC overrides (where supported) are respected.\n- Helpful validation errors are thrown for missing OIDC settings.\n- The IAM template files contain the expected resources and outputs.\n\nRun tests with:\n\n```bash\nyarn test\n```\n\n## Monorepo support\n\nIf your CDK app lives in a subdirectory (e.g., `infra/`), use the `workingDirectory` option:\n\n```ts\nnew CdkDiffStackWorkflow({\n  project,\n  workingDirectory: 'infra',\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'MyStack-dev',\n      changesetRoleToAssumeArn: 'arn:aws:iam::222222222222:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n    },\n  ],\n});\n\nnew CdkDriftDetectionWorkflow({\n  project,\n  workingDirectory: 'infra',\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'MyStack-dev',\n      driftDetectionRoleToAssumeArn: 'arn:aws:iam::222222222222:role/CdkDriftRole',\n      driftDetectionRoleToAssumeRegion: 'us-east-1',\n    },\n  ],\n});\n```\n\nThis sets `defaults.run.working-directory: infra` on all workflow jobs so that `install`, `synth`, and `deploy` steps run in the correct directory. The describe-changeset and detect-drift scripts are referenced with absolute paths so they resolve correctly from the subdirectory.\n\n**Note:** Your `infra/package.json` must include `@aws-sdk/client-cloudformation` as a dependency for the describe-changeset script to resolve modules at runtime.\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 scripts use the AWS SDK v3 for CloudFormation and, where applicable, the GitHub REST API.\n"
+    "markdown": "# cdk-diff-pr-github-action\n\nA [Projen](https://projen.io/) construct library that surfaces **CloudFormation change set diffs and drift status directly on your pull requests** so reviewers can see exactly what will change before merging.\n\n## Why this exists\n\n`cdk diff` output disappears into CI logs that nobody reads. Meanwhile, a single property change on an RDS instance or EC2 \"pet\" server can trigger a **resource replacement** — destroying the database or instance and recreating it from scratch. If that replacement slips through code review unnoticed, the result is data loss and downtime.\n\nThis construct was built to make those dangerous changes impossible to miss:\n\n- **Replacement column front and center** — Every change set row shows whether CloudFormation will modify the resource in place or **replace** it, with before/after property values so reviewers can understand *why*.\n- **Comment appears on the PR itself** — No digging through workflow logs. The diff table is posted (and updated in place) as a PR comment and in the GitHub Step Summary.\n- **Drift banner** — If the stack has drifted from its template, a warning banner is prepended to the comment so reviewers know the baseline is already out of sync.\n\nIf you have ever lost an EC2 instance, an RDS database, or an ElastiCache cluster to an unexpected CloudFormation replacement, this tool is for you.\n\n---\n\nA library that provides GitHub workflows and IAM templates for:\n- Creating CloudFormation Change Sets for your CDK stacks on pull requests and commenting a formatted diff back on the PR.\n- Detecting CloudFormation drift on a schedule or manual trigger and producing a consolidated summary (optionally creating an issue).\n- Deploying IAM roles across AWS Organizations using StackSets.\n\nIt also provides ready-to-deploy IAM templates with the minimal permissions required for each workflow.\n\n**Works with or without Projen** -- The StackSet generator can be used standalone in any Node.js project.\n\nThis package exposes five constructs:\n\n- `CdkDiffStackWorkflow` — Generates one GitHub Actions workflow per stack to create a change set and render the diff back to the PR and Step Summary.\n- `CdkDiffIamTemplate` — Emits a CloudFormation template file with minimal permissions for the Change Set workflow.\n- `CdkDriftDetectionWorkflow` — Generates a GitHub Actions workflow to detect CloudFormation drift per stack, upload machine‑readable results, and aggregate a summary.\n- `CdkDriftIamTemplate` — Emits a CloudFormation template file with minimal permissions for the Drift Detection workflow.\n- `CdkDiffIamTemplateStackSet` — Creates a CloudFormation StackSet template for org-wide deployment of GitHub OIDC and IAM roles (Projen integration).\n- `CdkDiffIamTemplateStackSetGenerator` — Pure generator class for StackSet templates (no Projen dependency).\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 or run the drift detection workflow.\n\n## End-to-end example\n\nA realistic setup for a CDK Pipelines project with multiple stages and accounts. This generates one diff workflow per stack, a shared IAM template, and a scheduled drift detection workflow.\n\n```ts\n// .projenrc.ts\nimport { awscdk } from 'projen';\nimport {\n  CdkDiffStackWorkflow,\n  CdkDiffIamTemplate,\n  CdkDriftDetectionWorkflow,\n} from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkTypeScriptApp({\n  name: 'my-data-platform',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.170.0',\n  github: true,\n});\n\n// --- Change Set Diff Workflows (one per stack) ---\n// stackName is the CDK construct path used with `cdk deploy <target>`.\n// For CDK Pipelines, this is typically: pipeline/Stage/Stack\n// The construct automatically resolves the real CloudFormation stack name\n// from cdk.out at runtime (e.g., \"my-stage-dev-my-stack\").\n\nnew CdkDiffStackWorkflow({\n  project,\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'my-pipeline/dev/DatabaseStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::111111111111:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n    },\n    {\n      stackName: 'my-pipeline/dev/ComputeStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::111111111111:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n    },\n    {\n      // Cross-account: prod stacks can use a different OIDC role and region\n      stackName: 'my-pipeline/prod/DatabaseStack',\n      changesetRoleToAssumeArn: 'arn:aws:iam::222222222222:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n      oidcRoleArn: 'arn:aws:iam::222222222222:role/GitHubOIDCRole',\n      oidcRegion: 'us-east-1',\n    },\n  ],\n});\n\n// --- IAM Template (deploy once per account) ---\nnew CdkDiffIamTemplate({\n  project,\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['my-data-platform'],\n    branches: ['main'],\n  },\n});\n\n// --- Drift Detection (scheduled + manual) ---\nnew CdkDriftDetectionWorkflow({\n  project,\n  schedule: '0 6 * * 1', // Every Monday at 6 AM UTC\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'dev-DatabaseStack',\n      driftDetectionRoleToAssumeArn: 'arn:aws:iam::111111111111:role/CdkDriftRole',\n      driftDetectionRoleToAssumeRegion: 'us-east-1',\n    },\n  ],\n});\n\nproject.synth();\n```\n\nAfter `npx projen`, this generates:\n- `.github/workflows/diff-my-pipeline-dev-databasestack.yml`\n- `.github/workflows/diff-my-pipeline-dev-computestack.yml`\n- `.github/workflows/diff-my-pipeline-prod-databasestack.yml`\n- `.github/workflows/scripts/describe-cfn-changeset.ts`\n- `.github/workflows/drift-detection.yml`\n- `.github/workflows/scripts/detect-drift.ts`\n- `cdk-diff-workflow-iam-template.yaml`\n\nWhen a pull request is opened, each diff workflow runs automatically and posts a comment like this:\n\n| Action | ID | Type | Replacement | Details |\n|--------|-----|------|-------------|---------|\n| 🔵 Modify | MyDatabase | AWS::RDS::DBInstance | **True** | 🔵 **DBInstanceClass**: `db.t3.medium` -> `db.t3.large` |\n| 🔵 Modify | MyFunction | AWS::Lambda::Function | False | 🔵 **Runtime**: `nodejs18.x` -> `nodejs20.x` |\n\nThe **Replacement: True** on the RDS instance is exactly the kind of change this tool is designed to catch before it reaches production.\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  workflowName: 'my-lib',\n  defaultReleaseBranch: 'main',\n  cdkVersion: '2.85.0',\n  github: true,\n});\n\nnew CdkDiffStackWorkflow({\n  project,\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: '24.x',\n  // Optional: Yarn command to run CDK (default: 'cdk')\n  // cdkYarnCommand: 'cdk',\n  // Optional: Where to place the helper script (default: '.github/workflows/scripts/describe-cfn-changeset.ts')\n  // scriptOutputPath: '.github/workflows/scripts/describe-cfn-changeset.ts',\n});\n\nproject.synth();\n```\n\n### CdkDiffStackWorkflow props\n- `project` (required) — Your Projen project instance.\n- `stacks` (required) — Array of stack entries.\n- `oidcRoleArn` (required unless provided per‑stack) — Default OIDC role ARN.\n- `oidcRegion` (required unless provided per‑stack) — Default OIDC region.\n- `nodeVersion` (optional, default `'24.x'`) — Node.js version for the workflow runner.\n- `cdkYarnCommand` (optional, default `'cdk'`) — Yarn script/command to invoke CDK.\n- `scriptOutputPath` (optional, default `'.github/workflows/scripts/describe-cfn-changeset.ts'`) — Where to write the helper script.\n- `workingDirectory` (optional) — Subdirectory where the CDK app lives (e.g., `'infra'`). Sets `defaults.run.working-directory` on all jobs so `install`, `synth`, and `deploy` steps run in that directory. The describe-changeset script path is automatically prefixed with `$GITHUB_WORKSPACE/` and `NODE_PATH` is set to resolve modules from the working directory.\n- `preGitHubSteps` (optional) — Additional steps to run after install but before AWS credentials and CDK operations. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`.\n- `postGitHubSteps` (optional) — Additional steps to run after all CDK operations complete. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`.\n\nIf neither top‑level OIDC defaults nor all per‑stack values are supplied, the construct throws a helpful error.\n\n### Stack item fields\n- `stackName` (required) — The CDK stack name to create the change set for.\n- `changesetRoleToAssumeArn` (required) — The ARN of the role used to create the change set (role chaining after OIDC).\n- `changesetRoleToAssumeRegion` (required) — 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  - **Checks cached drift status** via `DescribeStacks` — if the stack has drifted, a warning banner with drifted resource details is prepended to the output (non-fatal; degrades gracefully if IAM permissions are missing)\n  - Prints the HTML and appends to the GitHub Step Summary\n  - **Upserts the PR comment** — uses an HTML marker (`<!-- cdk-diff:stack:STACK_NAME -->`) to find and update an existing comment instead of creating duplicates on every push\n\n### Change Set Output Format\n\nThe change set script uses the CloudFormation `IncludePropertyValues` API feature to show **actual before/after values** for changed properties, not just property names.\n\n**Example PR comment:**\n\n> **Warning: Stack has drifted (2 resources out of sync)**\n>\n> Last drift check: 2025-01-15T10:30:00.000Z\n>\n> <details><summary>View drifted resources</summary>\n>\n> | Resource | Type | Drift Status |\n> |----------|------|-------------|\n> | MySecurityGroup | AWS::EC2::SecurityGroup | MODIFIED |\n> | OldBucket | AWS::S3::Bucket | DELETED |\n> </details>\n\n| Action | ID | Type | Replacement | Details |\n|--------|-----|------|-------------|---------|\n| 🔵 Modify | MyDatabase | AWS::RDS::DBInstance | **True** | 🔵 **DBInstanceClass**: `db.t3.medium` -> `db.t3.large` |\n| 🔵 Modify | MyLambdaFunction | AWS::Lambda::Function | False | 🔵 **Runtime**: `nodejs18.x` -> `nodejs20.x` |\n| 🟢 Add | NewSecurityGroup | AWS::EC2::SecurityGroup | - | |\n| 🔴 Remove | OldRole | AWS::IAM::Role | - | |\n\n**Features:**\n- **Replacement column** highlights when CloudFormation will **destroy and recreate** a resource — critical for stateful resources like databases, EC2 instances, and file systems\n- **Drift banner** — if the stack has drifted, a warning with drifted resource details appears above the change set table so reviewers know the baseline state\n- **Comment upsert** — each stack's comment is updated in place on subsequent pushes instead of creating duplicates; uses an HTML marker for reliable find-and-replace\n- **Color-coded indicators**: 🟢 Added, 🔵 Modified, 🔴 Removed\n- **Inline values for small changes**: Shows `before -> after` directly in the table\n- **Collapsible details for large values**: IAM policies, tags, and other large JSON values are wrapped in expandable `<details>` elements to keep the table readable\n- **All attribute types supported**: Properties, Tags, Metadata, etc.\n- **HTML-escaped values**: Prevents XSS from property values\n\n### Environment variables used by the change set 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(s).\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\nEmit an IAM template you can deploy in your account for the Change Set workflow. Supports two modes:\n\n1. **External OIDC Role** — Reference an existing GitHub OIDC role (original behavior)\n2. **Self-Contained** — Create the GitHub OIDC provider and role within the same template (new)\n\n### Option 1: Using an Existing OIDC Role (External)\n\nUse this when you already have a GitHub OIDC provider and role set up in your account.\n\n#### With Projen\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({\n  project,\n  roleName: 'cdk-diff-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: custom output path (default: 'cdk-diff-workflow-iam-template.yaml')\n  // outputPath: 'infra/cdk-diff-iam.yaml',\n});\n\nproject.synth();\n```\n\n#### Without Projen (Standalone Generator)\n\n```ts\nimport { CdkDiffIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\nconst template = CdkDiffIamTemplateGenerator.generateTemplate({\n  roleName: 'cdk-diff-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n});\n\nfs.writeFileSync('cdk-diff-iam-template.yaml', template);\n```\n\n### Option 2: Self-Contained Template (Create OIDC Role)\n\nUse this when you want a single template that creates everything needed — the GitHub OIDC provider, OIDC role, and changeset role. This simplifies deployment and pairs well with the `CdkDiffStackWorkflow`.\n\n#### With Projen\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({\n  project,\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  oidcRoleName: 'GitHubOIDCRole',  // Optional, default: 'GitHubOIDCRole'\n  githubOidc: {\n    owner: 'my-org',                          // GitHub org or username\n    repositories: ['infra-repo', 'app-repo'], // Repos allowed to assume roles\n    branches: ['main', 'release/*'],          // Branch patterns (default: ['*'])\n  },\n  // Optional: Skip OIDC provider creation if it already exists\n  // skipOidcProviderCreation: true,\n});\n\nproject.synth();\n```\n\n#### Without Projen (Standalone Generator)\n\n```ts\nimport { CdkDiffIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\nconst template = CdkDiffIamTemplateGenerator.generateTemplate({\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  oidcRoleName: 'GitHubOIDCRole',\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['infra-repo'],\n    branches: ['main'],\n  },\n});\n\nfs.writeFileSync('cdk-diff-iam-template.yaml', template);\n```\n\n#### With Existing OIDC Provider (Skip Creation)\n\nIf your account already has a GitHub OIDC provider but you want the template to create the roles:\n\n```ts\nnew CdkDiffIamTemplate({\n  project,\n  roleName: 'CdkChangesetRole',\n  createOidcRole: true,\n  skipOidcProviderCreation: true,  // Account already has OIDC provider\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['*'],  // All repos in org\n  },\n});\n```\n\n### Deploy Task\n\nA Projen task is added for easy deployment:\n\n```bash\nnpx projen deploy-cdkdiff-iam-template -- --parameter-overrides GitHubOIDCRoleArn=... # plus any extra AWS CLI args\n```\n\n### CdkDiffIamTemplate Props\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `roleName` | `string` | Name for the changeset IAM role (required) |\n| `oidcRoleArn` | `string?` | ARN of existing GitHub OIDC role. Required when `createOidcRole` is false. |\n| `oidcRegion` | `string?` | Region for OIDC trust condition. Required when `createOidcRole` is false. |\n| `createOidcRole` | `boolean?` | Create OIDC role within template (default: false) |\n| `oidcRoleName` | `string?` | Name of OIDC role to create (default: 'GitHubOIDCRole') |\n| `githubOidc` | `GitHubOidcConfig?` | GitHub OIDC config. Required when `createOidcRole` is true. |\n| `skipOidcProviderCreation` | `boolean?` | Skip OIDC provider if it exists (default: false) |\n| `outputPath` | `string?` | Template output path (default: 'cdk-diff-workflow-iam-template.yaml') |\n\n### What the Template Creates\n\n**External OIDC Role mode:**\n- Parameter `GitHubOIDCRoleArn` — ARN of your existing GitHub OIDC role\n- IAM role `CdkChangesetRole` with minimal permissions for change set operations\n- Outputs: `CdkChangesetRoleArn`, `CdkChangesetRoleName`\n\n**Self-Contained mode (`createOidcRole: true`):**\n- GitHub OIDC Provider (unless `skipOidcProviderCreation: true`)\n- IAM role `GitHubOIDCRole` with trust policy for GitHub Actions\n- IAM role `CdkChangesetRole` with minimal permissions (trusts the OIDC role)\n- Outputs: `GitHubOIDCProviderArn`, `GitHubOIDCRoleArn`, `GitHubOIDCRoleName`, `CdkChangesetRoleArn`, `CdkChangesetRoleName`\n\n**Changeset Role Permissions:**\n- CloudFormation Change Set operations\n- Access to CDK bootstrap S3 buckets and SSM parameters\n- `iam:PassRole` to `cloudformation.amazonaws.com`\n\nUse the created changeset role ARN as `changesetRoleToAssumeArn` in `CdkDiffStackWorkflow`.\n\n---\n\n## Usage: CdkDriftDetectionWorkflow\n\n`CdkDriftDetectionWorkflow` creates a single workflow file (default `drift-detection.yml`) that can run on a schedule and via manual dispatch. It generates a helper script at `.github/workflows/scripts/detect-drift.ts` (by default) that uses AWS SDK v3 to run drift detection, write optional machine‑readable JSON, and print an HTML report for the Step Summary.\n\nExample `.projenrc.ts`:\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDriftDetectionWorkflow } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({ github: true, /* ... */ });\n\nnew CdkDriftDetectionWorkflow({\n  project,\n  workflowName: 'Drift Detection',            // optional; file name derived as 'drift-detection.yml'\n  schedule: '0 1 * * *',                      // optional cron\n  createIssues: true,                         // default true; create/update issue when drift detected on schedule\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: Node version (default '24.x')\n  // nodeVersion: '24.x',\n  // Optional: Where to place the helper script (default '.github/workflows/scripts/detect-drift.ts')\n  // scriptOutputPath: '.github/workflows/scripts/detect-drift.ts',\n  stacks: [\n    {\n      stackName: 'MyAppStack-Prod',\n      driftDetectionRoleToAssumeArn: 'arn:aws:iam::123456789012:role/cdk-drift-role',\n      driftDetectionRoleToAssumeRegion: 'us-east-1',\n      // failOnDrift: true, // optional (default true)\n    },\n  ],\n});\n\nproject.synth();\n```\n\n### CdkDriftDetectionWorkflow props\n- `project` (required) — Your Projen project instance.\n- `stacks` (required) — Array of stacks to check.\n- `oidcRoleArn` (required) — Default OIDC role ARN used before chaining into per‑stack drift roles.\n- `oidcRegion` (required) — Default OIDC region.\n- `workflowName` (optional, default `'drift-detection'`) — Human‑friendly workflow name; the file name is derived in kebab‑case.\n- `schedule` (optional) — Cron expression for automatic runs.\n- `createIssues` (optional, default `true`) — When true, scheduled runs will create/update a GitHub issue if drift is detected.\n- `nodeVersion` (optional, default `'24.x'`) — Node.js version for the runner.\n- `scriptOutputPath` (optional, default `'.github/workflows/scripts/detect-drift.ts'`) — Where to write the helper script.\n- `workingDirectory` (optional) — Subdirectory where the CDK app lives (e.g., `'infra'`). Sets `defaults.run.working-directory` on all jobs. Artifact upload and issue-script paths are automatically prefixed.\n- `preGitHubSteps` (optional) — Additional steps to run after install but before AWS credentials and drift detection. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`. Pre-steps automatically receive the stack-selection condition so they only run when the stack is selected.\n- `postGitHubSteps` (optional) — Additional steps to run after drift detection and issue creation. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`. Steps default to `if: always() && steps.drift.outcome == 'failure'` unless you provide your own `if`.\n\n### Per‑stack fields\n- `stackName` (required) — The full CloudFormation stack name.\n- `driftDetectionRoleToAssumeArn` (required) — Role to assume (after OIDC) for making drift API calls.\n- `driftDetectionRoleToAssumeRegion` (required) — Region for that role and API calls.\n- `failOnDrift` (optional, default `true`) — Intended to fail the detection step on drift. The provided script exits with non‑zero when drift is found; the job continues to allow artifact upload and issue creation.\n\n### What gets generated\n- `.github/workflows/<kebab(workflowName)>.yml` — A workflow with one job per stack plus a final summary job.\n- `.github/workflows/scripts/detect-drift.ts` — Helper script that:\n  - Starts drift detection and polls until completion\n  - Lists non‑`IN_SYNC` resources and builds an HTML report\n  - Writes optional JSON to `DRIFT_DETECTION_OUTPUT` when set\n  - Prints to stdout and appends to the GitHub Step Summary when available\n\n### Artifacts and summary\n- Each stack job uploads `drift-results-<stack>.json` (if produced).\n- A final `Drift Detection Summary` job downloads all artifacts and prints a consolidated summary.\n\n### Manual dispatch\n- The workflow exposes an input named `stack` with choices including each configured stack and an `all` option.\n- Choose a specific stack to run drift detection for that stack only, or select `all` (or leave the input empty) to run all stacks.\n\nNote: The default workflow does not post PR comments for drift. It can create/update an Issue on scheduled runs when `createIssues` is `true`.\n\n### Post-notification steps (e.g., Slack)\n\nYou can add your own GitHub Action steps to run after the drift detection step for each stack using `postGitHubSteps`.\nProvide your own Slack payload/markdown (this library no longer generates a payload step for you).\n\nOption A: slackapi/slack-github-action (Incoming Webhook, official syntax)\n\n```ts\nnew CdkDriftDetectionWorkflow({\n  project,\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  stacks: [/* ... */],\n  postGitHubSteps: ({ stack }) => {\n    // Build a descriptive name per stack\n    const name = `Notify Slack (${stack} post-drift)`;\n    const step = {\n      name,\n      uses: 'slackapi/slack-github-action@v2.1.1',\n      // by default, post steps run only when drift is detected; you can override `if`\n      if: \"always() && steps.drift.outcome == 'failure'\",\n      // Use official inputs: webhook + webhook-type, and a YAML payload with blocks\n      with: {\n        webhook: '${{ secrets.CDK_NOTIFICATIONS_SLACK_WEBHOOK }}',\n        'webhook-type': 'incoming-webhook',\n        payload: [\n          'text: \"** ${{ env.STACK_NAME }} ** has drifted!\"',\n          'blocks:',\n          '  - type: \"section\"',\n          '    text:',\n          '      type: \"mrkdwn\"',\n          '      text: \"*Stack:* ${{ env.STACK_NAME }} (region ${{ env.AWS_REGION }}) has drifted:exclamation:\"',\n          '  - type: \"section\"',\n          '    fields:',\n          '      - type: \"mrkdwn\"',\n          '        text: \"*Stack ARN*\\\\n${{ steps.drift.outputs.stack-arn }}\"',\n          '      - type: \"mrkdwn\"',\n          '        text: \"*Issue*\\\\n<${{ github.server_url }}/${{ github.repository }}/issues/${{ steps.issue.outputs.result }}|#${{ steps.issue.outputs.result }}>\"',\n        ].join('\\n'),\n      },\n    };\n    return [step];\n  },\n});\n```\n\nNote: The Issue link requires `createIssues: true` (default) so that the `Create Issue on Drift` step runs before this Slack step and exposes `steps.issue.outputs.result`. This library orders the steps accordingly.\n\nDetails:\n- `postGitHubSteps` can be:\n  - an array of step objects, or\n  - a factory function `({ stack }) => step | step[]`.\n- Each step you provide is inserted after the results are uploaded.\n- Default condition: if you do not set `if` on your step, it will default to `always() && steps.drift.outcome == 'failure'`.\n- Available context/env you can use:\n  - `${{ env.STACK_NAME }}`, `${{ env.DRIFT_DETECTION_OUTPUT }}`\n  - `${{ steps.drift.outcome }}` — success/failure of the detect step\n  - `${{ steps.drift.outputs.stack-arn }}` — Stack ARN resolved at runtime\n  - `${{ steps.issue.outputs.result }}` — Issue number if the workflow created/found one (empty when not applicable)\n```\n\n## Usage: CdkDriftIamTemplate\n\nEmit an example IAM template you can deploy in your account for the Drift Detection workflow.\n\n### With Projen\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDriftIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({\n  // ...\n});\n\nnew CdkDriftIamTemplate({\n  project,\n  roleName: 'cdk-drift-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n  // Optional: custom output path (default: 'cdk-drift-workflow-iam-template.yaml')\n  // outputPath: 'infra/cdk-drift-iam.yaml',\n});\n\nproject.synth();\n```\n\nA Projen task is also added:\n\n```bash\nnpx projen deploy-cdkdrift-iam-template -- --parameter-overrides GitHubOIDCRoleArn=... # plus any extra AWS CLI args\n```\n\n### Without Projen (Standalone Generator)\n\n```ts\nimport { CdkDriftIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\nconst template = CdkDriftIamTemplateGenerator.generateTemplate({\n  roleName: 'cdk-drift-role',\n  oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',\n  oidcRegion: 'us-east-1',\n});\n\nfs.writeFileSync('cdk-drift-iam-template.yaml', template);\n\n// Get the deploy command\nconst deployCmd = CdkDriftIamTemplateGenerator.generateDeployCommand('cdk-drift-iam-template.yaml');\nconsole.log('Deploy with:', deployCmd);\n```\n\n### What the template defines\n\n- Parameter `GitHubOIDCRoleArn` with a default from `oidcRoleArn` — the ARN of your existing GitHub OIDC role allowed to assume this drift role.\n- IAM role `CdkDriftRole` with minimal permissions for CloudFormation drift detection operations.\n- Outputs exporting the role name and ARN.\n\n---\n\n## Usage: CdkDiffIamTemplateStackSet (Org-Wide Deployment)\n\n`CdkDiffIamTemplateStackSet` creates a CloudFormation StackSet template for deploying GitHub OIDC provider, OIDC role, and CDK diff/drift IAM roles across an entire AWS Organization. This is the recommended approach for organizations that want to enable CDK diff/drift workflows across multiple accounts.\n\n### Architecture\n\nEach account in your organization gets:\n- **GitHub OIDC Provider** — Authenticates GitHub Actions workflows\n- **GitHubOIDCRole** — Trusts the OIDC provider with repo/branch restrictions\n- **CdkChangesetRole** — For PR change set previews (trusts GitHubOIDCRole)\n- **CdkDriftRole** — For drift detection (trusts GitHubOIDCRole)\n\nThis is a self-contained deployment with **no role chaining required**.\n\n### With Projen\n\n```ts\nimport { awscdk } from 'projen';\nimport { CdkDiffIamTemplateStackSet } from '@jjrawlins/cdk-diff-pr-github-action';\n\nconst project = new awscdk.AwsCdkConstructLibrary({ /* ... */ });\n\nnew CdkDiffIamTemplateStackSet({\n  project,\n  githubOidc: {\n    owner: 'my-org',                          // GitHub org or username\n    repositories: ['infra-repo', 'app-repo'], // Repos allowed to assume roles\n    branches: ['main', 'release/*'],          // Branch patterns (default: ['*'])\n  },\n  targetOrganizationalUnitIds: ['ou-xxxx-xxxxxxxx'], // Target OUs\n  regions: ['us-east-1', 'eu-west-1'],               // Target regions\n  // Optional settings:\n  // oidcRoleName: 'GitHubOIDCRole',       // default\n  // changesetRoleName: 'CdkChangesetRole', // default\n  // driftRoleName: 'CdkDriftRole',         // default\n  // roleSelection: StackSetRoleSelection.BOTH, // BOTH, CHANGESET_ONLY, or DRIFT_ONLY\n  // delegatedAdmin: true,                  // Use --call-as DELEGATED_ADMIN (default: true)\n});\n\nproject.synth();\n```\n\nThis creates:\n- `cdk-diff-workflow-stackset-template.yaml` — CloudFormation template\n- Projen tasks for StackSet management\n\n**Projen tasks:**\n```bash\nnpx projen stackset-create          # Create the StackSet\nnpx projen stackset-update          # Update the StackSet template\nnpx projen stackset-deploy-instances # Deploy to target OUs/regions\nnpx projen stackset-delete-instances # Remove stack instances\nnpx projen stackset-delete          # Delete the StackSet\nnpx projen stackset-describe        # Show StackSet status\nnpx projen stackset-list-instances  # List all instances\n```\n\n### Without Projen (Standalone Generator)\n\nFor non-Projen projects, use `CdkDiffIamTemplateStackSetGenerator` directly:\n\n```ts\nimport {\n  CdkDiffIamTemplateStackSetGenerator\n} from '@jjrawlins/cdk-diff-pr-github-action';\nimport * as fs from 'fs';\n\n// Generate the CloudFormation template\nconst template = CdkDiffIamTemplateStackSetGenerator.generateTemplate({\n  githubOidc: {\n    owner: 'my-org',\n    repositories: ['infra-repo'],\n    branches: ['main'],\n  },\n});\n\n// Write to file\nfs.writeFileSync('stackset-template.yaml', template);\n\n// Get AWS CLI commands for StackSet operations\nconst commands = CdkDiffIamTemplateStackSetGenerator.generateCommands({\n  stackSetName: 'cdk-diff-workflow-iam-stackset',\n  templatePath: 'stackset-template.yaml',\n  targetOrganizationalUnitIds: ['ou-xxxx-xxxxxxxx'],\n  regions: ['us-east-1'],\n});\n\nconsole.log('Create StackSet:', commands['stackset-create']);\nconsole.log('Deploy instances:', commands['stackset-deploy-instances']);\n```\n\n### GitHub Actions Workflow (Simplified)\n\nWith per-account OIDC, your workflow is simplified — no role chaining needed:\n\n```yaml\njobs:\n  diff:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n\n      - uses: aws-actions/configure-aws-credentials@v4\n        with:\n          role-to-assume: arn:aws:iam::${{ env.ACCOUNT_ID }}:role/GitHubOIDCRole\n          aws-region: us-east-1\n\n      - name: Assume Changeset Role\n        run: |\n          CREDS=$(aws sts assume-role \\\n            --role-arn arn:aws:iam::${{ env.ACCOUNT_ID }}:role/CdkChangesetRole \\\n            --role-session-name changeset-session)\n          # Export credentials...\n```\n\n### GitHubOidcConfig options\n\n| Property | Description |\n|----------|-------------|\n| `owner` | GitHub organization or username (required) |\n| `repositories` | Array of repo names, or `['*']` for all repos (required) |\n| `branches` | Array of branch patterns (default: `['*']`) |\n| `additionalClaims` | Extra OIDC claims like `['pull_request', 'environment:production']` |\n\n---\n\n## Testing\n\nThis repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:\n- Diff workflows are created per stack and contain all expected steps.\n- Drift detection workflow produces one job per stack and a summary job.\n- Only one helper script file is generated per workflow type.\n- Per‑stack OIDC overrides (where supported) are respected.\n- Helpful validation errors are thrown for missing OIDC settings.\n- The IAM template files contain the expected resources and outputs.\n\nRun tests with:\n\n```bash\nyarn test\n```\n\n## Monorepo support\n\nIf your CDK app lives in a subdirectory (e.g., `infra/`), use the `workingDirectory` option:\n\n```ts\nnew CdkDiffStackWorkflow({\n  project,\n  workingDirectory: 'infra',\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'MyStack-dev',\n      changesetRoleToAssumeArn: 'arn:aws:iam::222222222222:role/CdkChangesetRole',\n      changesetRoleToAssumeRegion: 'us-east-1',\n    },\n  ],\n});\n\nnew CdkDriftDetectionWorkflow({\n  project,\n  workingDirectory: 'infra',\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [\n    {\n      stackName: 'MyStack-dev',\n      driftDetectionRoleToAssumeArn: 'arn:aws:iam::222222222222:role/CdkDriftRole',\n      driftDetectionRoleToAssumeRegion: 'us-east-1',\n    },\n  ],\n});\n```\n\nThis sets `defaults.run.working-directory: infra` on all workflow jobs so that `install`, `synth`, and `deploy` steps run in the correct directory. The describe-changeset and detect-drift scripts are referenced with absolute paths so they resolve correctly from the subdirectory.\n\n**Note:** Your `infra/package.json` must include `@aws-sdk/client-cloudformation` as a dependency for the describe-changeset script to resolve modules at runtime.\n\n## Pre/post workflow steps\n\nBoth `CdkDiffStackWorkflow` and `CdkDriftDetectionWorkflow` support `preGitHubSteps` and `postGitHubSteps` for running custom steps before and after CDK operations. This is useful for building source code, sending Slack notifications, or running arbitrary commands.\n\nYou can provide a static array of steps, or a factory function that receives context:\n\n```ts\nnew CdkDiffStackWorkflow({\n  project,\n  workingDirectory: 'infra',\n  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',\n  oidcRegion: 'us-east-1',\n  stacks: [/* ... */],\n  preGitHubSteps: ({ stack, workingDirectory }) => [\n    // Build at project root (overrides working-directory default)\n    { name: 'Build app', run: 'npm run build', 'working-directory': '.' },\n  ],\n  postGitHubSteps: ({ stack }) => [\n    { name: 'Notify Slack', uses: 'slackapi/slack-github-action@v2', with: { /* ... */ } },\n  ],\n});\n```\n\n> **Note:** When `workingDirectory` is set, all `run:` steps inherit that directory by default. To run a step at the repository root, add `working-directory: '.'` to that step.\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 scripts use the AWS SDK v3 for CloudFormation and, where applicable, the GitHub REST API.\n"
   },
   "repository": {
     "type": "git",
@@ -4376,7 +4376,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/CdkDiffStackWorkflow.ts",
-        "line": 11
+        "line": 23
       },
       "name": "CdkDiffStack",
       "properties": [
@@ -4388,7 +4388,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 13
+            "line": 25
           },
           "name": "changesetRoleToAssumeArn",
           "type": {
@@ -4403,7 +4403,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 14
+            "line": 26
           },
           "name": "changesetRoleToAssumeRegion",
           "type": {
@@ -4418,7 +4418,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 12
+            "line": 24
           },
           "name": "stackName",
           "type": {
@@ -4433,7 +4433,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 16
+            "line": 28
           },
           "name": "oidcRegion",
           "optional": true,
@@ -4449,7 +4449,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 15
+            "line": 27
           },
           "name": "oidcRoleArn",
           "optional": true,
@@ -4472,7 +4472,7 @@
         },
         "locationInModule": {
           "filename": "src/CdkDiffStackWorkflow.ts",
-          "line": 41
+          "line": 71
         },
         "parameters": [
           {
@@ -4486,7 +4486,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/CdkDiffStackWorkflow.ts",
-        "line": 38
+        "line": 68
       },
       "name": "CdkDiffStackWorkflow",
       "symbolId": "src/CdkDiffStackWorkflow:CdkDiffStackWorkflow"
@@ -4501,7 +4501,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/CdkDiffStackWorkflow.ts",
-        "line": 19
+        "line": 31
       },
       "name": "CdkDiffStackWorkflowProps",
       "properties": [
@@ -4513,7 +4513,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 20
+            "line": 32
           },
           "name": "project",
           "type": {
@@ -4528,7 +4528,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 21
+            "line": 33
           },
           "name": "stacks",
           "type": {
@@ -4548,7 +4548,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 25
+            "line": 37
           },
           "name": "cdkYarnCommand",
           "optional": true,
@@ -4564,7 +4564,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 24
+            "line": 36
           },
           "name": "nodeVersion",
           "optional": true,
@@ -4580,7 +4580,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 23
+            "line": 35
           },
           "name": "oidcRegion",
           "optional": true,
@@ -4596,7 +4596,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 22
+            "line": 34
           },
           "name": "oidcRoleArn",
           "optional": true,
@@ -4604,6 +4604,42 @@
             "primitive": "string"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Accepts a static array of steps, or a factory function receiving context:\n`(ctx: { stack: string; workingDirectory?: string }) => GitHubStep[]`\n\nWhen `workingDirectory` is set, all `run:` steps inherit that directory.\nTo run a step at the repository root, add `working-directory: '.'` to that step.",
+            "stability": "experimental",
+            "summary": "Additional GitHub Actions steps to run after all CDK operations complete."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffStackWorkflow.ts",
+            "line": 66
+          },
+          "name": "postGitHubSteps",
+          "optional": true,
+          "type": {
+            "primitive": "any"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Accepts a static array of steps, or a factory function receiving context:\n`(ctx: { stack: string; workingDirectory?: string }) => GitHubStep[]`\n\nWhen `workingDirectory` is set, all `run:` steps inherit that directory.\nTo run a step at the repository root, add `working-directory: '.'` to that step.",
+            "stability": "experimental",
+            "summary": "Additional GitHub Actions steps to run before CDK operations (after install, before AWS creds)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffStackWorkflow.ts",
+            "line": 57
+          },
+          "name": "preGitHubSteps",
+          "optional": true,
+          "type": {
+            "primitive": "any"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -4612,7 +4648,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 26
+            "line": 38
           },
           "name": "scriptOutputPath",
           "optional": true,
@@ -4631,7 +4667,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffStackWorkflow.ts",
-            "line": 36
+            "line": 48
           },
           "name": "workingDirectory",
           "optional": true,
@@ -4654,7 +4690,7 @@
         },
         "locationInModule": {
           "filename": "src/CdkDriftDetectionWorkflow.ts",
-          "line": 75
+          "line": 87
         },
         "parameters": [
           {
@@ -4668,7 +4704,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/CdkDriftDetectionWorkflow.ts",
-        "line": 72
+        "line": 84
       },
       "name": "CdkDriftDetectionWorkflow",
       "symbolId": "src/CdkDriftDetectionWorkflow:CdkDriftDetectionWorkflow"
@@ -4804,6 +4840,24 @@
             "primitive": "any"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Accepts a static array of steps, or a factory function receiving context:\n`(ctx: { stack: string; workingDirectory?: string }) => GitHubStep[]`\n\nWhen `workingDirectory` is set, all `run:` steps inherit that directory.\nTo run a step at the repository root, add `working-directory: '.'` to that step.\n\nPre-steps automatically receive the stack-selection condition (`if`) so they\nonly run when the stack is selected via dispatch.",
+            "stability": "experimental",
+            "summary": "Additional GitHub Actions steps to run before drift detection (after install, before AWS creds)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDriftDetectionWorkflow.ts",
+            "line": 69
+          },
+          "name": "preGitHubSteps",
+          "optional": true,
+          "type": {
+            "primitive": "any"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -5401,6 +5455,6 @@
       "symbolId": "src/CdkDiffIamTemplateStackSet:StackSetRoleSelection"
     }
   },
-  "version": "1.8.0",
-  "fingerprint": "gOPm1rvgC24rKxRefMcHRBmTZTxskniMczkswaBzoY4="
+  "version": "1.9.0",
+  "fingerprint": "TSOSxDZa5reP5/7kL692PAaEgLo68kfbJNX2QLyeRUY="
 }

package/API.md

@@ -796,6 +796,8 @@ const cdkDiffStackWorkflowProps: CdkDiffStackWorkflowProps = { ... }
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.nodeVersion">nodeVersion</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.oidcRegion">oidcRegion</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.oidcRoleArn">oidcRoleArn</a></code> | <code>string</code> | *No description.* |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.postGitHubSteps">postGitHubSteps</a></code> | <code>any</code> | Additional GitHub Actions steps to run after all CDK operations complete. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.preGitHubSteps">preGitHubSteps</a></code> | <code>any</code> | Additional GitHub Actions steps to run before CDK operations (after install, before AWS creds). |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.scriptOutputPath">scriptOutputPath</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.workingDirectory">workingDirectory</a></code> | <code>string</code> | Working directory for the CDK app, relative to the repository root. |
 
@@ -861,6 +863,42 @@ public readonly oidcRoleArn: string;
 
 ---
 
+##### `postGitHubSteps`<sup>Optional</sup> <a name="postGitHubSteps" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.postGitHubSteps"></a>
+
+```typescript
+public readonly postGitHubSteps: any;
+```
+
+- *Type:* any
+
+Additional GitHub Actions steps to run after all CDK operations complete.
+
+Accepts a static array of steps, or a factory function receiving context:
+`(ctx: { stack: string; workingDirectory?: string }) => GitHubStep[]`
+
+When `workingDirectory` is set, all `run:` steps inherit that directory.
+To run a step at the repository root, add `working-directory: '.'` to that step.
+
+---
+
+##### `preGitHubSteps`<sup>Optional</sup> <a name="preGitHubSteps" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.preGitHubSteps"></a>
+
+```typescript
+public readonly preGitHubSteps: any;
+```
+
+- *Type:* any
+
+Additional GitHub Actions steps to run before CDK operations (after install, before AWS creds).
+
+Accepts a static array of steps, or a factory function receiving context:
+`(ctx: { stack: string; workingDirectory?: string }) => GitHubStep[]`
+
+When `workingDirectory` is set, all `run:` steps inherit that directory.
+To run a step at the repository root, add `working-directory: '.'` to that step.
+
+---
+
 ##### `scriptOutputPath`<sup>Optional</sup> <a name="scriptOutputPath" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffStackWorkflowProps.property.scriptOutputPath"></a>
 
 ```typescript
@@ -910,6 +948,7 @@ const cdkDriftDetectionWorkflowProps: CdkDriftDetectionWorkflowProps = { ... }
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.oidcRegion">oidcRegion</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.oidcRoleArn">oidcRoleArn</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.postGitHubSteps">postGitHubSteps</a></code> | <code>any</code> | Optional additional GitHub Action steps to run after drift detection for each stack. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.preGitHubSteps">preGitHubSteps</a></code> | <code>any</code> | Additional GitHub Actions steps to run before drift detection (after install, before AWS creds). |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.schedule">schedule</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.scriptOutputPath">scriptOutputPath</a></code> | <code>string</code> | *No description.* |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.workflowName">workflowName</a></code> | <code>string</code> | *No description.* |
@@ -993,6 +1032,27 @@ directly in your step without relying on a pre-generated payload.
 
 ---
 
+##### `preGitHubSteps`<sup>Optional</sup> <a name="preGitHubSteps" id="@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.preGitHubSteps"></a>
+
+```typescript
+public readonly preGitHubSteps: any;
+```
+
+- *Type:* any
+
+Additional GitHub Actions steps to run before drift detection (after install, before AWS creds).
+
+Accepts a static array of steps, or a factory function receiving context:
+`(ctx: { stack: string; workingDirectory?: string }) => GitHubStep[]`
+
+When `workingDirectory` is set, all `run:` steps inherit that directory.
+To run a step at the repository root, add `working-directory: '.'` to that step.
+
+Pre-steps automatically receive the stack-selection condition (`if`) so they
+only run when the stack is selected via dispatch.
+
+---
+
 ##### `schedule`<sup>Optional</sup> <a name="schedule" id="@jjrawlins/cdk-diff-pr-github-action.CdkDriftDetectionWorkflowProps.property.schedule"></a>
 
 ```typescript

package/README.md

@@ -194,6 +194,8 @@ project.synth();
 - `cdkYarnCommand` (optional, default `'cdk'`) — Yarn script/command to invoke CDK.
 - `scriptOutputPath` (optional, default `'.github/workflows/scripts/describe-cfn-changeset.ts'`) — Where to write the helper script.
 - `workingDirectory` (optional) — Subdirectory where the CDK app lives (e.g., `'infra'`). Sets `defaults.run.working-directory` on all jobs so `install`, `synth`, and `deploy` steps run in that directory. The describe-changeset script path is automatically prefixed with `$GITHUB_WORKSPACE/` and `NODE_PATH` is set to resolve modules from the working directory.
+- `preGitHubSteps` (optional) — Additional steps to run after install but before AWS credentials and CDK operations. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`.
+- `postGitHubSteps` (optional) — Additional steps to run after all CDK operations complete. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`.
 
 If neither top‑level OIDC defaults nor all per‑stack values are supplied, the construct throws a helpful error.
 
@@ -465,6 +467,8 @@ project.synth();
 - `nodeVersion` (optional, default `'24.x'`) — Node.js version for the runner.
 - `scriptOutputPath` (optional, default `'.github/workflows/scripts/detect-drift.ts'`) — Where to write the helper script.
 - `workingDirectory` (optional) — Subdirectory where the CDK app lives (e.g., `'infra'`). Sets `defaults.run.working-directory` on all jobs. Artifact upload and issue-script paths are automatically prefixed.
+- `preGitHubSteps` (optional) — Additional steps to run after install but before AWS credentials and drift detection. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`. Pre-steps automatically receive the stack-selection condition so they only run when the stack is selected.
+- `postGitHubSteps` (optional) — Additional steps to run after drift detection and issue creation. Accepts a static array or a factory `({ stack, workingDirectory }) => steps[]`. Steps default to `if: always() && steps.drift.outcome == 'failure'` unless you provide your own `if`.
 
 ### Per‑stack fields
 - `stackName` (required) — The full CloudFormation stack name.
@@ -793,6 +797,31 @@ This sets `defaults.run.working-directory: infra` on all workflow jobs so that `
 
 **Note:** Your `infra/package.json` must include `@aws-sdk/client-cloudformation` as a dependency for the describe-changeset script to resolve modules at runtime.
 
+## Pre/post workflow steps
+
+Both `CdkDiffStackWorkflow` and `CdkDriftDetectionWorkflow` support `preGitHubSteps` and `postGitHubSteps` for running custom steps before and after CDK operations. This is useful for building source code, sending Slack notifications, or running arbitrary commands.
+
+You can provide a static array of steps, or a factory function that receives context:
+
+```ts
+new CdkDiffStackWorkflow({
+  project,
+  workingDirectory: 'infra',
+  oidcRoleArn: 'arn:aws:iam::111111111111:role/GitHubOIDCRole',
+  oidcRegion: 'us-east-1',
+  stacks: [/* ... */],
+  preGitHubSteps: ({ stack, workingDirectory }) => [
+    // Build at project root (overrides working-directory default)
+    { name: 'Build app', run: 'npm run build', 'working-directory': '.' },
+  ],
+  postGitHubSteps: ({ stack }) => [
+    { name: 'Notify Slack', uses: 'slackapi/slack-github-action@v2', with: { /* ... */ } },
+  ],
+});
+```
+
+> **Note:** When `workingDirectory` is set, all `run:` steps inherit that directory by default. To run a step at the repository root, add `working-directory: '.'` to that step.
+
 ## Notes
 - This package assumes your repository is configured with GitHub Actions and that you have a GitHub OIDC role configured in AWS.
 - The generated scripts use the AWS SDK v3 for CloudFormation and, where applicable, the GitHub REST API.

package/cdkdiffprgithubaction/CdkDiffStackWorkflowProps.go

@@ -17,5 +17,15 @@ type CdkDiffStackWorkflowProps struct {
 	OidcRoleArn *string `field:"optional" json:"oidcRoleArn" yaml:"oidcRoleArn"`
 	// Experimental.
 	ScriptOutputPath *string `field:"optional" json:"scriptOutputPath" yaml:"scriptOutputPath"`
+	// Working directory for the CDK app, relative to the repository root.
+	//
+	// Useful for monorepos where infrastructure lives in a subdirectory (e.g., 'infra').
+	//
+	// When set, all workflow run steps will use `defaults.run.working-directory`
+	// and script paths will be adjusted to use absolute references.
+	// Default: - repository root.
+	//
+	// Experimental.
+	WorkingDirectory *string `field:"optional" json:"workingDirectory" yaml:"workingDirectory"`
 }
 

package/cdkdiffprgithubaction/CdkDriftDetectionWorkflowProps.go

@@ -28,5 +28,15 @@ type CdkDriftDetectionWorkflowProps struct {
 	ScriptOutputPath *string `field:"optional" json:"scriptOutputPath" yaml:"scriptOutputPath"`
 	// Experimental.
 	WorkflowName *string `field:"optional" json:"workflowName" yaml:"workflowName"`
+	// Working directory for the CDK app, relative to the repository root.
+	//
+	// Useful for monorepos where infrastructure lives in a subdirectory (e.g., 'infra').
+	//
+	// When set, all workflow run steps will use `defaults.run.working-directory`
+	// and artifact/script paths will be adjusted accordingly.
+	// Default: - repository root.
+	//
+	// Experimental.
+	WorkingDirectory *string `field:"optional" json:"workingDirectory" yaml:"workingDirectory"`
 }