Install

Scaffold the project, configure it with Projen, bootstrap your AWS environment, and deploy your first CDK stack.

Prerequisites

  • Node.js 22.18 (match the repo's .nvmrc for local parity) and npm
  • AWS CLI logged in to the target accounts (SSO or short-lived credentials both work)
  • AWS CDK v2 available via npx cdk (no global install required)
  • Optional but recommended: a GitHub fine-grained PAT stored as the PROJEN_GITHUB_TOKEN secret so Projen can auto-approve bot PRs

1) Fork & clone the starter kit

git clone https://github.com/towardsthecloud/aws-cdk-starter-kit my-cdk-app
cd my-cdk-app
npm ci

If you fork the repo, point the origin remote at your fork before installing dependencies.

2) Personalize .projenrc.ts

.projenrc.ts is the single source of truth for everything the repo generates. Update it before generating files so the automation reflects your team (see Configuration > Environments for the full breakdown):

  • Project identity: Change name, description, and author metadata so published packages, generated docs, and release notes use your branding.
  • Deployment safety: Update awsRegion and githubRole to point to regions and IAM roles you actually control; this prevents the workflows from deploying into placeholder accounts.
  • Environment matrix: Replace the placeholder environmentConfigs entries with the AWS account IDs and branch-deploy preferences for each stage (e.g., test, production). These drive the npm scripts and GitHub workflows that Projen emits.
  • Optional automation: If you plan to let Dependabot PRs auto-merge, keep autoApproveOptions and ensure you'll later supply the matching PAT secret.
const awsRegion = process.env.AWS_REGION || 'us-east-1';
const environmentConfigs = [
  { name: 'test', accountId: '123456789012', enableBranchDeploy: true },
  { name: 'production', accountId: '210987654321', enableBranchDeploy: false },
];

Swap in your preferred default region and the real AWS account IDs before continuing.

Each entry generates npm scripts such as npm run test:deploy, npm run test:synth, and matching GitHub Actions workflows.

3) Synthesize configuration with Projen

Projen consumes .projenrc.ts and rewrites configuration files, scripts, and workflows. Run it any time you change the config so those outputs stay in sync:

npx projen

When you add an environment entry, for example, Projen will:

  • regenerate package.json scripts like npm run staging:deploy with the right CDK_DEFAULT_ACCOUNT, CDK_DEFAULT_REGION, and GIT_BRANCH_REF environment variables;
  • create/update GitHub Actions workflows so pull requests and main-branch pushes deploy the new environment automatically;
  • refresh linting/formatting config, Dependabot settings, and any other artifacts derived from the project definition.

That single command keeps the repo deterministic—never hand-edit the generated files, always edit .projenrc.ts and rerun Projen instead. To inspect everything Projen created, run npx projen --help for a list of generated tasks.

4) Authenticate and bootstrap AWS

Ensure the AWS CLI is authenticated against each account listed in environmentConfigs, then bootstrap the CDK toolkit stack once per account/region pair:

npx cdk bootstrap aws://<ACCOUNT_ID>/<REGION>

5) Deploy from your workstation

Use the generated npm scripts to deploy the helper stack (GitHub OIDC role) and the starter stacks for each environment.

First, make sure your CLI session is assuming a role with the right permissions—if you rely on AWS SSO, follow our guide on setting up the AWS CLI with AWS SSO.

The initial deployment must come from your workstation so the FoundationStack can create the GitHub OIDC IAM role your pipelines rely on:

npm run test:synth
npm run test:diff
npm run test:deploy

Repeat for additional environments such as production (npm run production:deploy). For branch previews, see the Environments guide.

Ready for the day-to-day loop? Check out Guides > Local Development for the recurring commands to run before opening a pull request.

6) Push to GitHub and enable CI/CD

After the initial local deploy, you can commit your changes and push to your default branch (typically main). In the generated workflow, a step similar to the snippet below uses GitHub OIDC to assume the role that Projen configured for your environment:

name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4
with:
  role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/GitHubActionsServiceRole
  aws-region: us-east-1

GitHub OIDC uses the role created by the foundation stack, letting the workflow authenticate to your AWS account without long-lived keys. Swap <ACCOUNT_ID> for one of the accounts you configured in step 2 when reading the example. For a deeper walkthrough of what happens on push, read Guides > CI/CD Workflow.

Learn more about the pattern: How to set up GitHub OIDC federation for AWS deployments.

← OverviewConfiguration →