Updating Versions

The landing zone foundation and constructs are delivered as versioned packages through AWS CodeArtifact. When Towards The Cloud releases improvements, you receive them by bumping two pinned version numbers in .projenrc.ts and redeploying, with no forking or patching required.

Pinned versions

The two licensed packages are pinned in the towardsTheCloudPackages array in .projenrc.ts; the CDK versions are set on the cdkVersion and cdkCliVersion fields:

The two licensed packages are excluded from automated dependency upgrades (depsUpgradeOptions.exclude), so you bump them by hand when a release is announced.

Upgrade procedure

1. Check the release notes: Towards The Cloud communicates breaking changes and migration steps with each release.

2. Update the version pins in .projenrc.ts:

   const towardsTheCloudPackages = [
     { name: '@towardsthecloud/cdk-landing-zone-constructs', version: '1.10.0' }, // bump here
     { name: '@towardsthecloud/cdk-landing-zone-foundation', version: '1.9.0' }, // and here
   ];
   

   For a CDK bump, update cdkVersion and cdkCliVersion in the same file instead.

3. Regenerate project files and install the new packages:

   pnpm exec projen
   

   This rewrites package.json, pnpm-lock.yaml, and generated files to match the new pins.

4. Review the diff: git diff will show which generated files changed. Pay particular attention to changes in .github/workflows/ and any generated npm scripts.

5. Deploy: the first command deploys the organization phase to the management account, and the second deploys the landing-zone phase to the landing zone account.

   pnpm run organization:deploy
   pnpm run landingzone:deploy:all
   

   Or push to main and let the GitHub Actions pipeline deploy.

Automated dependency upgrades

projen generates an upgrade workflow (.github/workflows/upgrade.yml) that keeps your non-licensed dependencies current on its own. It runs on a daily schedule and can also be triggered manually from the repository's Actions tab. Each run executes pnpm exec projen upgrade and, when something changed, opens a pull request titled chore(deps): upgrade dependencies on the github-actions/upgrade branch for you to review and merge.

The two licensed @towardsthecloud packages are excluded from this workflow (depsUpgradeOptions.exclude), so it never bumps them. It upgrades everything else: the AWS CDK library and CLI, projen, and your other dev and runtime dependencies. Landing zone releases still go through the manual upgrade procedure above.

Required setup: the pull-request step authenticates with a PROJEN_GITHUB_TOKEN repository secret. Add it under your repository's Settings → Secrets and variables → Actions as a GitHub token (a personal access token, or equivalent) with permission to create pull requests. Without it, the upgrade job still computes the dependency changes, but the follow-up job cannot open the pull request, so the run finishes without one.

CodeArtifact token refresh

The pnpm exec projen step runs pnpm install internally, which requires a valid CodeArtifact token. If the install fails with a 401 error:

# Re-assume your management account role, then:
pnpm run setup

pnpm run setup fetches a fresh token and re-runs the install.

Things to know

• Both packages should be bumped together: cdk-landing-zone-foundation and cdk-landing-zone-constructs are released in tandem and tested against each other at the same version.
• CDK version bumps (cdkVersion and cdkCliVersion) follow the same pattern. Check the AWS CDK changelog for breaking changes before bumping.
• Projen re-runs on install: generated files are regenerated automatically when you run pnpm exec projen. Committing the resulting changes to main keeps the repo consistent.