Environments

Overview

Environments are modeled in .projenrc.ts using an environmentConfigs array. Projen generates npm scripts and GitHub Actions so each environment gets the correct account, region, and permissions.

Projen-first configuration

Define environments in .projenrc.ts at the repository root:

const environmentConfigs: (EnvironmentConfig & { name: Environment })[] = [
  { name: 'test',       accountId: '987654321012', enableBranchDeploy: true },
  { name: 'production', accountId: '123456789012', enableBranchDeploy: false },
];

for (const config of environmentConfigs) {
  // Adds npm run scripts for synth/test/deploy/diff per environment
  addCdkActionTask(project, {
    CDK_DEFAULT_ACCOUNT: config.accountId,
    CDK_DEFAULT_REGION: awsRegion,
    ENVIRONMENT: config.name,
    GITHUB_DEPLOY_ROLE: githubRole,
  });

  // Generate GitHub Actions for this environment
  createCdkDeploymentWorkflows(
    project.github,
    config.accountId,
    awsRegion,
    config.name,
    githubRole,
    nodeVersion,
    config.enableBranchDeploy,
    orderedEnvironments,
  );
}

After editing .projenrc.ts, run npx projen to regenerate tasks and workflows.

Reading environment context in stacks

Your stacks read the environment from task-injected variables:

// src/main.ts
import * as cdk from 'aws-cdk-lib';
import { createEnvResourceName } from './bin/env-helper';
import { StarterStack } from './stacks';

const app = new cdk.App();
const env = {
  account: process.env.CDK_DEFAULT_ACCOUNT,
  region: process.env.CDK_DEFAULT_REGION,
};

new StarterStack(app, createEnvResourceName('StarterStack'), {
  env,
  environment: process.env.ENVIRONMENT,
});

Environment variables

Each generated npm script sets consistent variables your stacks can read at runtime:

You can rely on these in src/main.ts, constructs, or aspects without manually wiring additional context.

Ephemeral environments

Per-branch preview environments are built in. Set enableBranchDeploy: true for an environment to enable branch deploys.

How it works:

1. Tasks inject GIT_BRANCH_REF and suffix stack names
2. IAM role trust policy allows branch refs like refs/heads/feature/*
3. Workflows compute a safe branch suffix
4. On branch deletion, cleanup job destroys the branch stack

Why this helps:

• Rapid previews - See real infrastructure behavior without impacting shared environments
• Parallel testing - Multiple feature branches can test changes concurrently
• Safer changes - Experiment freely, easy to destroy when done
• Clear ownership - Resources tagged and named by branch

Local branch deploy example

The generated npm tasks auto-set GIT_BRANCH_REF from your current branch:

# Create and switch to a feature branch
git checkout -b feature/cool-thing

# Preview resources for the branch
npm run test:branch:synth
npm run test:branch:diff:stack StarterStack

# Deploy only StarterStack for this branch
npm run test:branch:deploy:stack StarterStack

# List deployed stacks (shows branch-suffixed names)
npm run test:branch:ls

# Cleanup when done
npm run test:branch:destroy:stack StarterStack

For the full workflow including GitHub Actions, see Branch-based Development.

Note: FoundationStack is intentionally excluded from branch deploys.

Bootstrap per environment

Run npx cdk bootstrap once per account/region pair before the first deploy:

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

This creates the CDK toolkit stack used for assets and deployments. See the Install guide for details.

Adding a new environment

1. Add the environment to environmentConfigs in .projenrc.ts:

{ name: 'staging', accountId: '111222333444', enableBranchDeploy: false },

2. Regenerate tasks and workflows:

npx projen

3. Bootstrap the new account:

npx cdk bootstrap aws://111222333444/us-east-1

4. Deploy the FoundationStack to create the OIDC role:

npm run staging:deploy

Next steps

• CI/CD Workflows - Understand deployment automation
• Branch-based Development - Full preview workflow
• Helpers reference - createEnvResourceName and other utilities