@jjrawlins/cdk-diff-pr-github-action 1.1.5 → 1.2.0

package/.jsii

@@ -7,7 +7,7 @@
     ]
   },
   "bundled": {
-    "@aws-sdk/client-cloudformation": "^3.981.0",
+    "@aws-sdk/client-cloudformation": "^3.982.0",
     "@types/crypto-js": "^4.2.2",
     "@types/js-yaml": "^4.0.9",
     "crypto-js": "^4.2.0",
@@ -3549,7 +3549,7 @@
   },
   "name": "@jjrawlins/cdk-diff-pr-github-action",
   "readme": {
-    "markdown": "# cdk-diff-pr-github-action\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## 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\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  - 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 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 example IAM template you can deploy in your account for the Change Set workflow.\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\nA Projen task is also added:\n\n```bash\nnpx projen deploy-cdkdiff-iam-template -- --parameter-overrides GitHubOIDCRoleArn=... # plus any extra AWS CLI args\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// Get the deploy command\nconst deployCmd = CdkDiffIamTemplateGenerator.generateDeployCommand('cdk-diff-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 the change set role.\n- 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\nUse the created 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\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## 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 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## 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\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  - 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 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\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## 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",
@@ -3576,7 +3576,7 @@
         },
         "locationInModule": {
           "filename": "src/CdkDiffIamTemplate.ts",
-          "line": 132
+          "line": 440
         },
         "parameters": [
           {
@@ -3590,7 +3590,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/CdkDiffIamTemplate.ts",
-        "line": 131
+        "line": 439
       },
       "name": "CdkDiffIamTemplate",
       "symbolId": "src/CdkDiffIamTemplate:CdkDiffIamTemplate"
@@ -3611,7 +3611,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/CdkDiffIamTemplate.ts",
-        "line": 19
+        "line": 56
       },
       "methods": [
         {
@@ -3621,7 +3621,7 @@
           },
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 110
+            "line": 87
           },
           "name": "generateDeployCommand",
           "parameters": [
@@ -3647,7 +3647,7 @@
           },
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 23
+            "line": 60
           },
           "name": "generateTemplate",
           "parameters": [
@@ -3680,22 +3680,76 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/CdkDiffIamTemplate.ts",
-        "line": 6
+        "line": 7
       },
       "name": "CdkDiffIamTemplateGeneratorProps",
       "properties": [
         {
           "abstract": true,
           "docs": {
+            "stability": "experimental",
+            "summary": "Name for the changeset IAM role."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 9
+          },
+          "name": "roleName",
+          "type": {
+            "primitive": "string"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "When true, githubOidc configuration is required and oidcRoleArn is ignored.\nDefault: false",
+            "stability": "experimental",
+            "summary": "Create a GitHub OIDC role within this template instead of using an existing one."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 28
+          },
+          "name": "createOidcRole",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Required when createOidcRole is true.",
+            "stability": "experimental",
+            "summary": "GitHub OIDC configuration for repo/branch restrictions."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 41
+          },
+          "name": "githubOidc",
+          "optional": true,
+          "type": {
+            "fqn": "@jjrawlins/cdk-diff-pr-github-action.GitHubOidcConfig"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Only used when oidcRoleArn is provided (external OIDC role).",
             "stability": "experimental",
             "summary": "Region for the OIDC trust condition."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 12
+            "line": 21
           },
           "name": "oidcRegion",
+          "optional": true,
           "type": {
             "primitive": "string"
           }
@@ -3703,15 +3757,17 @@
         {
           "abstract": true,
           "docs": {
+            "remarks": "Required when createOidcRole is false or undefined.",
             "stability": "experimental",
             "summary": "ARN of the existing GitHub OIDC role that can assume this changeset role."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 10
+            "line": 15
           },
           "name": "oidcRoleArn",
+          "optional": true,
           "type": {
             "primitive": "string"
           }
@@ -3719,18 +3775,38 @@
         {
           "abstract": true,
           "docs": {
+            "remarks": "Only used when createOidcRole is true.\nDefault: 'GitHubOIDCRole'",
             "stability": "experimental",
-            "summary": "Name for the IAM role."
+            "summary": "Name of the GitHub OIDC role to create."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 8
+            "line": 35
           },
-          "name": "roleName",
+          "name": "oidcRoleName",
+          "optional": true,
           "type": {
             "primitive": "string"
           }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "Set to true if the account already has a GitHub OIDC provider.\nOnly used when createOidcRole is true.\nDefault: false",
+            "stability": "experimental",
+            "summary": "Skip creating the OIDC provider (use existing one)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/CdkDiffIamTemplate.ts",
+            "line": 49
+          },
+          "name": "skipOidcProviderCreation",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
         }
       ],
       "symbolId": "src/CdkDiffIamTemplate:CdkDiffIamTemplateGeneratorProps"
@@ -3749,7 +3825,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/CdkDiffIamTemplate.ts",
-        "line": 118
+        "line": 426
       },
       "name": "CdkDiffIamTemplateProps",
       "properties": [
@@ -3762,7 +3838,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 120
+            "line": 428
           },
           "name": "project",
           "type": {
@@ -3778,7 +3854,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/CdkDiffIamTemplate.ts",
-            "line": 122
+            "line": 430
           },
           "name": "outputPath",
           "optional": true,
@@ -5317,6 +5393,6 @@
       "symbolId": "src/CdkDiffIamTemplateStackSet:StackSetRoleSelection"
     }
   },
-  "version": "1.1.5",
-  "fingerprint": "jhEiebiBnQd0TC/P1r6yX2ojtmoOI75GEhTFUgpYIJw="
+  "version": "1.2.0",
+  "fingerprint": "k2V9wsxAcvcUdeJ88MIQUs52YxCMRGagJv7XBJnWHRo="
 }

package/API.md

@@ -19,13 +19,58 @@ const cdkDiffIamTemplateGeneratorProps: CdkDiffIamTemplateGeneratorProps = { ...
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.roleName">roleName</a></code> | <code>string</code> | Name for the changeset IAM role. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.createOidcRole">createOidcRole</a></code> | <code>boolean</code> | Create a GitHub OIDC role within this template instead of using an existing one. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.githubOidc">githubOidc</a></code> | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.GitHubOidcConfig">GitHubOidcConfig</a></code> | GitHub OIDC configuration for repo/branch restrictions. |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRegion">oidcRegion</a></code> | <code>string</code> | Region for the OIDC trust condition. |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRoleArn">oidcRoleArn</a></code> | <code>string</code> | ARN of the existing GitHub OIDC role that can assume this changeset role. |
-| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.roleName">roleName</a></code> | <code>string</code> | Name for the IAM role. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRoleName">oidcRoleName</a></code> | <code>string</code> | Name of the GitHub OIDC role to create. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.skipOidcProviderCreation">skipOidcProviderCreation</a></code> | <code>boolean</code> | Skip creating the OIDC provider (use existing one). |
 
 ---
 
-##### `oidcRegion`<sup>Required</sup> <a name="oidcRegion" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRegion"></a>
+##### `roleName`<sup>Required</sup> <a name="roleName" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.roleName"></a>
+
+```typescript
+public readonly roleName: string;
+```
+
+- *Type:* string
+
+Name for the changeset IAM role.
+
+---
+
+##### `createOidcRole`<sup>Optional</sup> <a name="createOidcRole" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.createOidcRole"></a>
+
+```typescript
+public readonly createOidcRole: boolean;
+```
+
+- *Type:* boolean
+
+Create a GitHub OIDC role within this template instead of using an existing one.
+
+When true, githubOidc configuration is required and oidcRoleArn is ignored.
+Default: false
+
+---
+
+##### `githubOidc`<sup>Optional</sup> <a name="githubOidc" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.githubOidc"></a>
+
+```typescript
+public readonly githubOidc: GitHubOidcConfig;
+```
+
+- *Type:* <a href="#@jjrawlins/cdk-diff-pr-github-action.GitHubOidcConfig">GitHubOidcConfig</a>
+
+GitHub OIDC configuration for repo/branch restrictions.
+
+Required when createOidcRole is true.
+
+---
+
+##### `oidcRegion`<sup>Optional</sup> <a name="oidcRegion" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRegion"></a>
 
 ```typescript
 public readonly oidcRegion: string;
@@ -35,9 +80,11 @@ public readonly oidcRegion: string;
 
 Region for the OIDC trust condition.
 
+Only used when oidcRoleArn is provided (external OIDC role).
+
 ---
 
-##### `oidcRoleArn`<sup>Required</sup> <a name="oidcRoleArn" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRoleArn"></a>
+##### `oidcRoleArn`<sup>Optional</sup> <a name="oidcRoleArn" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRoleArn"></a>
 
 ```typescript
 public readonly oidcRoleArn: string;
@@ -47,17 +94,38 @@ public readonly oidcRoleArn: string;
 
 ARN of the existing GitHub OIDC role that can assume this changeset role.
 
+Required when createOidcRole is false or undefined.
+
 ---
 
-##### `roleName`<sup>Required</sup> <a name="roleName" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.roleName"></a>
+##### `oidcRoleName`<sup>Optional</sup> <a name="oidcRoleName" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.oidcRoleName"></a>
 
 ```typescript
-public readonly roleName: string;
+public readonly oidcRoleName: string;
 ```
 
 - *Type:* string
 
-Name for the IAM role.
+Name of the GitHub OIDC role to create.
+
+Only used when createOidcRole is true.
+Default: 'GitHubOIDCRole'
+
+---
+
+##### `skipOidcProviderCreation`<sup>Optional</sup> <a name="skipOidcProviderCreation" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateGeneratorProps.property.skipOidcProviderCreation"></a>
+
+```typescript
+public readonly skipOidcProviderCreation: boolean;
+```
+
+- *Type:* boolean
+
+Skip creating the OIDC provider (use existing one).
+
+Set to true if the account already has a GitHub OIDC provider.
+Only used when createOidcRole is true.
+Default: false
 
 ---
 
@@ -77,15 +145,60 @@ const cdkDiffIamTemplateProps: CdkDiffIamTemplateProps = { ... }
 
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.roleName">roleName</a></code> | <code>string</code> | Name for the changeset IAM role. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.createOidcRole">createOidcRole</a></code> | <code>boolean</code> | Create a GitHub OIDC role within this template instead of using an existing one. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.githubOidc">githubOidc</a></code> | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.GitHubOidcConfig">GitHubOidcConfig</a></code> | GitHub OIDC configuration for repo/branch restrictions. |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRegion">oidcRegion</a></code> | <code>string</code> | Region for the OIDC trust condition. |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRoleArn">oidcRoleArn</a></code> | <code>string</code> | ARN of the existing GitHub OIDC role that can assume this changeset role. |
-| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.roleName">roleName</a></code> | <code>string</code> | Name for the IAM role. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRoleName">oidcRoleName</a></code> | <code>string</code> | Name of the GitHub OIDC role to create. |
+| <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.skipOidcProviderCreation">skipOidcProviderCreation</a></code> | <code>boolean</code> | Skip creating the OIDC provider (use existing one). |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.project">project</a></code> | <code>any</code> | Projen project instance. |
 | <code><a href="#@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.outputPath">outputPath</a></code> | <code>string</code> | Output path for the template file (default: 'cdk-diff-workflow-iam-template.yaml'). |
 
 ---
 
-##### `oidcRegion`<sup>Required</sup> <a name="oidcRegion" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRegion"></a>
+##### `roleName`<sup>Required</sup> <a name="roleName" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.roleName"></a>
+
+```typescript
+public readonly roleName: string;
+```
+
+- *Type:* string
+
+Name for the changeset IAM role.
+
+---
+
+##### `createOidcRole`<sup>Optional</sup> <a name="createOidcRole" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.createOidcRole"></a>
+
+```typescript
+public readonly createOidcRole: boolean;
+```
+
+- *Type:* boolean
+
+Create a GitHub OIDC role within this template instead of using an existing one.
+
+When true, githubOidc configuration is required and oidcRoleArn is ignored.
+Default: false
+
+---
+
+##### `githubOidc`<sup>Optional</sup> <a name="githubOidc" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.githubOidc"></a>
+
+```typescript
+public readonly githubOidc: GitHubOidcConfig;
+```
+
+- *Type:* <a href="#@jjrawlins/cdk-diff-pr-github-action.GitHubOidcConfig">GitHubOidcConfig</a>
+
+GitHub OIDC configuration for repo/branch restrictions.
+
+Required when createOidcRole is true.
+
+---
+
+##### `oidcRegion`<sup>Optional</sup> <a name="oidcRegion" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRegion"></a>
 
 ```typescript
 public readonly oidcRegion: string;
@@ -95,9 +208,11 @@ public readonly oidcRegion: string;
 
 Region for the OIDC trust condition.
 
+Only used when oidcRoleArn is provided (external OIDC role).
+
 ---
 
-##### `oidcRoleArn`<sup>Required</sup> <a name="oidcRoleArn" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRoleArn"></a>
+##### `oidcRoleArn`<sup>Optional</sup> <a name="oidcRoleArn" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRoleArn"></a>
 
 ```typescript
 public readonly oidcRoleArn: string;
@@ -107,17 +222,38 @@ public readonly oidcRoleArn: string;
 
 ARN of the existing GitHub OIDC role that can assume this changeset role.
 
+Required when createOidcRole is false or undefined.
+
 ---
 
-##### `roleName`<sup>Required</sup> <a name="roleName" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.roleName"></a>
+##### `oidcRoleName`<sup>Optional</sup> <a name="oidcRoleName" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.oidcRoleName"></a>
 
 ```typescript
-public readonly roleName: string;
+public readonly oidcRoleName: string;
 ```
 
 - *Type:* string
 
-Name for the IAM role.
+Name of the GitHub OIDC role to create.
+
+Only used when createOidcRole is true.
+Default: 'GitHubOIDCRole'
+
+---
+
+##### `skipOidcProviderCreation`<sup>Optional</sup> <a name="skipOidcProviderCreation" id="@jjrawlins/cdk-diff-pr-github-action.CdkDiffIamTemplateProps.property.skipOidcProviderCreation"></a>
+
+```typescript
+public readonly skipOidcProviderCreation: boolean;
+```
+
+- *Type:* boolean
+
+Skip creating the OIDC provider (use existing one).
+
+Set to true if the account already has a GitHub OIDC provider.
+Only used when createOidcRole is true.
+Default: false
 
 ---