Stacks

Foundation and application stacks provided by the starter kit and how to run them via generated npm scripts.

FoundationStack

Source: src/stacks/foundation-stack.ts

Purpose

  • Sets up GitHub OpenID Connect (OIDC) and an IAM role for GitHub Actions deploys.
  • Adds a CloudFormation Toolkit cleaner to keep CDK assets tidy.

Key resources

  • iam.OpenIdConnectProvider for token.actions.githubusercontent.com with client ID sts.amazonaws.com.
  • iam.Role named GitHubActionsServiceRole by default, or override via GITHUB_DEPLOY_ROLE.
    • Trusts GitHub OIDC with subject: repo:<owner>/<repo>:environment:<ENV>.
  • ToolkitCleaner from cloudstructs.

Props

  • environment: string — environment label used in the OIDC subject (e.g., test, production).

Deployment behavior

  • Only synthesized when not running a branch deployment: guarded by if (!process.env.GIT_BRANCH_REF) in src/main.ts.
  • Deploy once per AWS account/region to enable OIDC deployments.

Usage

# Deploy Foundation + Starter stacks for test env
npm run test:deploy:all
 
# Or deploy just the FoundationStack
npm run test:deploy:stack FoundationStack

StarterStack

Source: src/stacks/starter-stack.ts

Purpose

  • Your application entry stack — add constructs and resources here.
  • Shows a commented example using NetworkConstruct for a secure VPC.

Props

  • environment?: string — used for tagging and resource naming in src/main.ts.

Usage

# Synthesize and diff only the starter stack
npm run test:synth
npm run test:diff:stack StarterStack
 
# Deploy only the starter stack
npm run test:deploy:stack StarterStack

Generated npm scripts (from .projenrc.ts)

Environment configs: test (branch deploys enabled) and production (branch deploys disabled).

Test (regular)

  • test:synth
  • test:ls
  • test:deploy:all | test:deploy:stack <StackName>
  • test:destroy:all | test:destroy:stack <StackName>
  • test:diff:all | test:diff:stack <StackName>

Test (branch)

  • test:branch:synth
  • test:branch:ls
  • test:branch:deploy:all | test:branch:deploy:stack <StackName>
  • test:branch:destroy:all | test:branch:destroy:stack <StackName>
  • test:branch:diff:all | test:branch:diff:stack <StackName>

Production

  • production:synth
  • production:ls
  • production:deploy:all | production:deploy:stack <StackName>
  • production:destroy:all | production:destroy:stack <StackName>
  • production:diff:all | production:diff:stack <StackName>

Notes

  • :all operates on all stacks in the app; :stack accepts stack names as args.
  • Branch tasks inject GIT_BRANCH_REF automatically (from git rev-parse --abbrev-ref HEAD) for safe name suffixing and isolation.
  • The FoundationStack is excluded from branch deploys by design.
← Helpers