Install

Overview

This guide walks you through scaffolding the CDK starter kit, configuring it for your AWS accounts, and deploying your first stack. By the end, you'll have a working CI/CD pipeline using GitHub OIDC.

Prerequisites

Before starting, ensure you have:

Optional but recommended: A GitHub fine-grained PAT stored as PROJEN_GITHUB_TOKEN so Projen can auto-approve bot PRs.

1. Fork and 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 running Projen so automation reflects your team.

What to customize:

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 real AWS account IDs. Each entry generates npm scripts like npm run test:deploy and matching GitHub Actions workflows.

For the full breakdown, see Configuration > Environments.

3. Synthesize configuration with Projen

Projen consumes .projenrc.ts and rewrites configuration files, scripts, and workflows:

npx projen

What Projen generates:

• package.json scripts with environment variables (CDK_DEFAULT_ACCOUNT, CDK_DEFAULT_REGION)
• GitHub Actions workflows for automated deployments
• Linting, formatting, and Dependabot configuration

Important: Never hand-edit generated files. Always edit .projenrc.ts and rerun Projen.

To see all generated tasks:

npx projen --help

4. Authenticate and bootstrap AWS

Ensure the AWS CLI is authenticated against each account in environmentConfigs, then bootstrap the CDK toolkit stack:

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

Bootstrap once per account/region pair. This creates the CDK toolkit stack used for assets and deployments.

5. Deploy from your workstation

Use the generated npm scripts to deploy the foundation stack (GitHub OIDC role) and starter stacks.

First, confirm your CLI session has the right permissions:

aws sts get-caller-identity

If you use AWS SSO, follow our guide on setting up the AWS CLI with AWS SSO.

Initial deployment (creates the OIDC role for CI/CD):

npm run test:synth      # synthesize CloudFormation templates
npm run test:diff       # preview changes
npm run test:deploy     # deploy all stacks

Note: The first deploy must come from your workstation so FoundationStack can create the GitHub OIDC IAM role.

Repeat for additional environments:

npm run production:deploy

For branch previews, see Environments > Ephemeral environments.

6. Push to GitHub and enable CI/CD

After the initial local deploy, commit and push to your default branch (typically main).

The generated workflow uses GitHub OIDC to assume the role created by FoundationStack:

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 authenticates without long-lived keys. For a deeper walkthrough, read How to configure OpenID Connect for GitHub in AWS CDK.

For details on what happens after push, see Configuration > CI/CD Workflows.

Next steps

• Local Development - Daily commands for building, testing, and deploying
• Environments - Multi-account configuration and branch previews
• Stacks reference - Understanding FoundationStack and StarterStack