Note: The default workflow does not post PR comments for drift. It can create/update an Issue on scheduled runs when createIssues is true.

$3

You can add your own GitHub Action steps to run after the drift detection step for each stack using postGitHubSteps.
Provide your own Slack payload/markdown (this library no longer generates a payload step for you).

Option A: slackapi/slack-github-action (Incoming Webhook, official syntax)

`ts
new CdkDriftDetectionWorkflow({
project,
oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',
oidcRegion: 'us-east-1',
stacks: [/ ... /],
postGitHubSteps: ({ stack }) => {
// Build a descriptive name per stack
const name = Notify Slack (${stack} post-drift);
const step = {
name,
uses: 'slackapi/slack-github-action@v2.1.1',
// by default, post steps run only when drift is detected; you can override if
if: "always() && steps.drift.outcome == 'failure'",
// Use official inputs: webhook + webhook-type, and a YAML payload with blocks
with: {
webhook: '${{ secrets.CDK_NOTIFICATIONS_SLACK_WEBHOOK }}',
'webhook-type': 'incoming-webhook',
payload: [
'text: " ${{ env.STACK_NAME }} has drifted!"',
'blocks:',
' - type: "section"',
' text:',
' type: "mrkdwn"',
' text: "Stack: ${{ env.STACK_NAME }} (region ${{ env.AWS_REGION }}) has drifted:exclamation:"',
' - type: "section"',
' fields:',
' - type: "mrkdwn"',
' text: "Stack ARN\\n${{ steps.drift.outputs.stack-arn }}"',
' - type: "mrkdwn"',
' text: "Issue\\n<${{ github.server_url }}/${{ github.repository }}/issues/${{ steps.issue.outputs.result }}|#${{ steps.issue.outputs.result }}>"',
].join('\n'),
},
};
return [step];
},
});
`

Note: 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.

Details:
- postGitHubSteps can be:
- an array of step objects, or
- a factory function ({ stack }) => step | step[].
- Each step you provide is inserted after the results are uploaded.
- Default condition: if you do not set if on your step, it will default to always() && steps.drift.outcome == 'failure'.
- Available context/env you can use:
- ${{ env.STACK_NAME }}, ${{ env.DRIFT_DETECTION_OUTPUT }}
- ${{ steps.drift.outcome }} — success/failure of the detect step
- ${{ steps.drift.outputs.stack-arn }} — Stack ARN resolved at runtime
- ${{ steps.issue.outputs.result }} — Issue number if the workflow created/found one (empty when not applicable)
`

Usage: CdkDriftIamTemplate

Emit an example IAM template you can deploy in your account for the Drift Detection workflow.

$3

`ts
import { awscdk } from 'projen';
import { CdkDriftIamTemplate } from '@jjrawlins/cdk-diff-pr-github-action';

const project = new awscdk.AwsCdkConstructLibrary({
// ...
});

new CdkDriftIamTemplate({
project,
roleName: 'cdk-drift-role',
oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',
oidcRegion: 'us-east-1',
// Optional: custom output path (default: 'cdk-drift-workflow-iam-template.yaml')
// outputPath: 'infra/cdk-drift-iam.yaml',
});

project.synth();
`

A Projen task is also added:

`bash
npx projen deploy-cdkdrift-iam-template -- --parameter-overrides GitHubOIDCRoleArn=... # plus any extra AWS CLI args
`

$3

`ts
import { CdkDriftIamTemplateGenerator } from '@jjrawlins/cdk-diff-pr-github-action';
import * as fs from 'fs';

const template = CdkDriftIamTemplateGenerator.generateTemplate({
roleName: 'cdk-drift-role',
oidcRoleArn: 'arn:aws:iam::123456789012:role/github-oidc-role',
oidcRegion: 'us-east-1',
});

fs.writeFileSync('cdk-drift-iam-template.yaml', template);

// Get the deploy command
const deployCmd = CdkDriftIamTemplateGenerator.generateDeployCommand('cdk-drift-iam-template.yaml');
console.log('Deploy with:', deployCmd);
`

$3

- Parameter GitHubOIDCRoleArn with a default from oidcRoleArn — the ARN of your existing GitHub OIDC role allowed to assume this drift role.
- IAM role CdkDriftRole with minimal permissions for CloudFormation drift detection operations.
- Outputs exporting the role name and ARN.

---

Usage: CdkDiffIamTemplateStackSet (Org-Wide Deployment)

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.

$3

Each account in your organization gets:
- GitHub OIDC Provider — Authenticates GitHub Actions workflows
- GitHubOIDCRole — Trusts the OIDC provider with repo/branch restrictions
- CdkChangesetRole — For PR change set previews (trusts GitHubOIDCRole)
- CdkDriftRole — For drift detection (trusts GitHubOIDCRole)

This is a self-contained deployment with no role chaining required.

$3

`ts
import { awscdk } from 'projen';
import { CdkDiffIamTemplateStackSet } from '@jjrawlins/cdk-diff-pr-github-action';

const project = new awscdk.AwsCdkConstructLibrary({ / ... / });

new CdkDiffIamTemplateStackSet({
project,
githubOidc: {
owner: 'my-org', // GitHub org or username
repositories: ['infra-repo', 'app-repo'], // Repos allowed to assume roles
branches: ['main', 'release/'], // Branch patterns (default: [''])
},
targetOrganizationalUnitIds: ['ou-xxxx-xxxxxxxx'], // Target OUs
regions: ['us-east-1', 'eu-west-1'], // Target regions
// Optional settings:
// oidcRoleName: 'GitHubOIDCRole', // default
// changesetRoleName: 'CdkChangesetRole', // default
// driftRoleName: 'CdkDriftRole', // default
// roleSelection: StackSetRoleSelection.BOTH, // BOTH, CHANGESET_ONLY, or DRIFT_ONLY
// delegatedAdmin: true, // Use --call-as DELEGATED_ADMIN (default: true)
});

project.synth();
`

This creates:
- cdk-diff-workflow-stackset-template.yaml — CloudFormation template
- Projen tasks for StackSet management

Projen tasks:
`bash
npx projen stackset-create # Create the StackSet
npx projen stackset-update # Update the StackSet template
npx projen stackset-deploy-instances # Deploy to target OUs/regions
npx projen stackset-delete-instances # Remove stack instances
npx projen stackset-delete # Delete the StackSet
npx projen stackset-describe # Show StackSet status
npx projen stackset-list-instances # List all instances
`

$3

For non-Projen projects, use CdkDiffIamTemplateStackSetGenerator directly:

`ts
import {
CdkDiffIamTemplateStackSetGenerator
} from '@jjrawlins/cdk-diff-pr-github-action';
import * as fs from 'fs';

// Generate the CloudFormation template
const template = CdkDiffIamTemplateStackSetGenerator.generateTemplate({
githubOidc: {
owner: 'my-org',
repositories: ['infra-repo'],
branches: ['main'],
},
});

// Write to file
fs.writeFileSync('stackset-template.yaml', template);

// Get AWS CLI commands for StackSet operations
const commands = CdkDiffIamTemplateStackSetGenerator.generateCommands({
stackSetName: 'cdk-diff-workflow-iam-stackset',
templatePath: 'stackset-template.yaml',
targetOrganizationalUnitIds: ['ou-xxxx-xxxxxxxx'],
regions: ['us-east-1'],
});

console.log('Create StackSet:', commands['stackset-create']);
console.log('Deploy instances:', commands['stackset-deploy-instances']);
`

$3

With per-account OIDC, your workflow is simplified — no role chaining needed:

`yaml
jobs:
diff:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v4

- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::${{ env.ACCOUNT_ID }}:role/GitHubOIDCRole
aws-region: us-east-1

- name: Assume Changeset Role
run: |
CREDS=$(aws sts assume-role \
--role-arn arn:aws:iam::${{ env.ACCOUNT_ID }}:role/CdkChangesetRole \
--role-session-name changeset-session)
# Export credentials...
`

$3

| Property | Description |
|----------|-------------|
| owner | GitHub organization or username (required) |
| repositories | Array of repo names, or ['*'] for all repos (required) |
| branches | Array of branch patterns (default: ['*']) |
| additionalClaims | Extra OIDC claims like ['pull_request', 'environment:production'] |

---

Testing

This repository includes Jest tests that snapshot the synthesized outputs from Projen and assert that:
- Diff workflows are created per stack and contain all expected steps.
- Drift detection workflow produces one job per stack and a summary job.
- Only one helper script file is generated per workflow type.
- Per‑stack OIDC overrides (where supported) are respected.
- Helpful validation errors are thrown for missing OIDC settings.
- The IAM template files contain the expected resources and outputs.

Run tests with:

`bash
yarn test
``

Notes