Branch-based Development

Overview

Branch-based deployments let every feature branch spin up its own copy of the stacks. Test infrastructure changes without touching shared environments.

Enable branch deploys

Set enableBranchDeploy: true on any environment in environmentConfigs (see Configuration > Environments):

{ name: 'test', accountId: '987654321012', enableBranchDeploy: true },

After running npx projen, the starter kit generates:

Generated	Purpose
`npm run test:branch:deploy:all`	Deploy stacks with branch suffix
`npm run test:branch:diff:stack`	Preview branch-specific changes
`cdk-deploy-<env>-branch` workflow	Auto-deploy on branch push
`cdk-destroy-<env>-branch` workflow	Cleanup on branch delete or manual dispatch

These tasks use helpers from env-helper.ts to inject GIT_BRANCH_REF and clean branch names safely.

Local workflow

# Create a feature branch
git checkout -b feature/payment-alerts

# Preview CloudFormation output
npm run test:branch:synth
npm run test:branch:diff:stack StarterStack

# Deploy stacks with branch suffixes
npm run test:branch:deploy:stack StarterStack

# Tear down when finished
npm run test:branch:destroy:stack StarterStack

The tasks automatically set GIT_BRANCH_REF from your current git branch. For day-to-day commands, see the Local Development guide.

GitHub Actions workflow

When you push the branch, the generated workflow:

Calculates branch identifier - Uses extractCleanedBranchName for safe naming
Runs synth and deploy - Stack names include the suffix (e.g., StarterStack-feature-payment-alerts)
Tags resources - Both environment and branch labels (handled in src/main.ts)
Auto-cleanup - Runs when branch is deleted (cdk-destroy-<env>-branch)

Manual cleanup is available through workflow dispatch.

Guardrails

Guardrail	Protection
Foundation stack exclusion	`FoundationStack` never deploys in branch mode
Main branch protection	`createEnvResourceName` throws if `GIT_BRANCH_REF` resolves to `main`
IAM trust policy	OIDC role must allow refs like `refs/heads/feature/*`

Clean exits

Always destroy branch stacks when you finish:

npm run test:branch:destroy:all

Warning: Leaving stacks active incurs cost and can delay subsequent deploys if resources collide.

The destroy workflow is idempotent - safe to run multiple times.

Next steps

CI/CD Workflows - Understand what happens after merge
Environments - Configure the environment matrix
Helpers reference - extractCleanedBranchName and createEnvResourceName