aws-cdk.md

AWS CDK

A streamlined AWS CDK workflow supporting multi-environment infrastructure synthesis, diffs and deployments with automatic package manager detection and Node.js version management.

Features

• CDK synth → diff → deploy workflow: Complete infrastructure deployment pipeline
• Multi-environment support: development, staging, and production deployments
• Bootstrap validation: Automatic CDK environment preparation and validation
• Changeset preview: CloudFormation diff analysis before deployment
• PR diff comments: When running a diff on a pull request, the result is posted (or updated) as a PR comment
• Smart Node.js setup: Automatic detection from .nvmrc file with dependency caching
• Package manager detection: Automatic support for npm, yarn (classic/berry), and pnpm
• Debug support: Verbose logging and debug output for troubleshooting
• GitHub Environments support: Credentials and stack names can be configured per-environment via GitHub Environment variables/secrets

Inputs

Name	Required	Type	Default	Description
Core Configuration
stack-name	❌	string		CDK stack name (overrides STACK_NAME variable if provided)
aws-region	❌	string	ap-southeast-2	AWS region for deployment
role-session-name	❌	string		AWS role session name for OIDC authentication (default: {repo}-{short-sha}-{run-number})
github-environment	❌	string	Repository	GitHub Environment name for secrets/variables (e.g., Staging, Production)
Deployment Control
bootstrap	❌	boolean	false	Bootstrap CDK environment before deployment
deploy	❌	boolean	false	Deploy stack
diff	❌	boolean	false	Diff stack
synth	❌	boolean	false	Synth stack
Advanced Configuration
context-values	❌	string	{}	CDK context values as JSON object
environment-target	❌	string		Target environment for CDK context (stg/prd/dev) - passed as --context environment=<value>
extra-arguments	❌	string		Extra arguments as string
debug	❌	boolean	false	Enable verbose logging and debug output
lfs	❌	boolean	false	Enable Git LFS support for checkout
Custom CDK Commands
bootstrap-command	❌	string	npx cdk bootstrap	Custom bootstrap command
synth-command	❌	string	npx cdk synth	Custom synth command
diff-command	❌	string	npx cdk diff	Custom diff command
deploy-command	❌	string	npx cdk deploy	Custom deploy command

Note: At least one of synth, diff, or deploy must be set to true for the workflow to run.

Variables and Secrets

These should be configured in your GitHub Environment (or at the repository level if not using environments).

Name	Required	Type	Description
STACK_NAME	❌	Variable	The name of the CloudFormation stack to deploy (required unless stack-name input is provided)
AWS_ACCESS_KEY_ID	❌	Variable	AWS Access Key ID (required for static credential auth)
AWS_SECRET_ACCESS_KEY	❌	Secret	AWS Secret Access Key (required for static credential auth)
AWS_ROLE_ARN	❌	Variable	AWS IAM role ARN (required for OIDC auth)
CFN_EXECUTION_ROLE	❌	Secret	CloudFormation execution role ARN (optional, for cross-account deployments with static credentials)

Authentication: Configure either static credentials (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY) or OIDC (AWS_ROLE_ARN). The workflow auto-detects which method to use.

Outputs

Name	Description
stack-outputs	CloudFormation stack outputs as JSON
deployment-status	Deployment status (success/failed)

Example Usage

Bootstrap New Environment:

on:
  push:
    branches:
      - staging

...

jobs:
  bootstrap-staging:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      bootstrap: true
      aws-region: us-east-1
    secrets: inherit

PR Diff (No Environment):

Note: pull-requests: write is required for the workflow to post diff comments on the PR.

on:
  pull_request:
    branches:
      - '**'

permissions:
  pull-requests: write
  contents: read

jobs:
  diff:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      diff: true
    secrets: inherit

PR Diff (Multiple Environments):

• Each environment should have its own STACK_NAME, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY configured.
• github.base_ref references the name of the target branch for staging and production.
• Each environment posts its own comment keyed on the stack name, so multiple diffs can coexist on the same PR.

on:
  pull_request:
    branches:
      - '**'

permissions:
  pull-requests: write
  contents: read

jobs:
  diff-staging:
    if: github.base_ref == 'staging'
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Staging
      diff: true
    secrets: inherit

  diff-production:
    if: github.base_ref == 'production'
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Production
      diff: true
    secrets: inherit

Staging Deployment:

on:
  push:
    branches:
      - staging

jobs: 
  deploy:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Staging
      deploy: true
    secrets: inherit

Production Deployment:

on:
  push:
    branches:
      - main

jobs:
  deploy:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Production
      deploy: true
    secrets: inherit

Deploy Staging in NX Monorepo:

on:
  push:
    branches:
      - staging

jobs:
  deploy:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Staging
      deploy: true
      deploy-command: yarn nx run core:cdk deploy
      secrets: inherit

Staging Deployment (OIDC):

Note: Calling workflows must set permissions: id-token: write at the workflow or job level for OIDC to function. Configure AWS_ROLE_ARN as a variable in your GitHub Environment.

on:
  push:
    branches:
      - staging

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Staging
      deploy: true
    secrets: inherit

Deploy Production in NX Monorepo from Release:

on:
  release:
    types: [published]

jobs:
  deploy:
    uses: aligent/workflows/.github/workflows/aws-cdk.yml@main
    with:
      github-environment: Production
      deploy: true
      deploy-command: yarn nx run core:cdk deploy
    secrets: inherit