CI/CD Workflow

Understand what happens after you push, how environments deploy in order, and how to interact with the GitHub Actions pipelines.

Overview

The starter kit ships with GitHub Actions workflows generated by Projen so every merge to your default branch produces a deterministic deploy. This guide explains the lifecycle from merge to rollout and how to interact with the pipelines.

Trigger flow

  1. Push or merge into main: Projen creates a workflow named cdk-deploy-<env> for each environment. The first environment in environmentConfigs (typically test) runs on every push to main.
  2. Environment chaining: Subsequent environments trigger via workflow_run when the previous deploy finishes successfully. For example, cdk-deploy-production waits for cdk-deploy-test to succeed before starting.
  3. Pull requests: Branch deploy workflows named cdk-deploy-<env>-branch run when enableBranchDeploy is true for that environment. They deploy stacks with branch suffixes so previews stay isolated. Cleanup is handled by cdk-destroy-<env>-branch on branch deletion or PR close.
  4. CDK diff on pull requests: The cdk-diff-pr-comment workflow runs automatically on every pull request targeting main. It generates a CDK diff comparing your PR branch against the production environment and posts the results as a comment directly in the pull request. This gives reviewers visibility into infrastructure changes before merging.
  5. Manual runs: Every workflow exposes the workflow_dispatch trigger, enabling re-runs or ad-hoc deploys straight from the GitHub Actions UI.

What each deploy job does

Inside the deploy job (see createCdkDeploymentWorkflows) GitHub Actions performs:

  • Checkout & setup: actions/checkout pulls the repo, then actions/setup-node installs the Node.js version from .projenrc.ts.
  • Install dependencies: npm ci installs dependencies exactly as defined in package-lock.json.
  • Assume the OIDC role: aws-actions/configure-aws-credentials@v4 exchanges the GitHub Actions identity for the IAM role created by FoundationStack.
  • Synth: Runs npm run <env>:synth, ensuring CloudFormation templates match expectations before deploying.
  • Deploy: Runs npm run <env>:deploy:all, deploying the stacks defined in src/main.ts to the target AWS account and region.

For branch deploy jobs, the same steps run, but Projen injects GIT_BRANCH_REF so stack names include a branch suffix. Destroy workflows call npm run <env>:branch:destroy:all with the proper branch reference.

CDK diff workflow

The cdk-diff-pr-comment workflow provides early visibility into infrastructure changes before they're merged:

  • Trigger: Runs on pull_request_target when opening or updating a PR against main.
  • Security: Uses pull_request_target to access repository secrets while checking out the PR branch SHA directly.
  • Diff generation: Runs npm run production:diff:all to compare the PR branch against the current production environment.
  • PR comment: Uses the towardsthecloud/aws-cdk-diff-pr-commenter action to post or update a comment with the diff output, including a custom header showing the environment and region.
  • Permissions: Requires contents: read, id-token: write (for OIDC authentication), and pull-requests: write (to post comments).

This workflow helps reviewers understand infrastructure changes at a glance without needing to run cdk diff locally.

Monitoring and troubleshooting

  • GitHub Actions UI: track the workflow progress directly in Actions. Logs show the exact Projen task executing so you can reproduce locally.
  • CloudFormation stack events: The stack names match createEnvResourceName('StackName'), so failures are easy to locate in the AWS console.
  • Rerunning: Use workflow_dispatch or the "Re-run jobs" button after fixing issues. Just ensure the branch you rerun from still matches the intended state.

Before you push

  • Run through the Local Development guide to synth/diff locally and keep formatting tidy.
  • If you changed .projenrc.ts, run npx projen so the generated workflows stay in sync with the new environment layout.

Advanced configuration

  • Edit environmentConfigs in .projenrc.ts to change deployment order, AWS accounts, or to opt environments in/out of branch deploys.
  • Need additional stages (for example, staging)? Add them to the array, rerun npx projen, and new cdk-deploy-<env> workflows will appear automatically.
  • To adjust step logic or concurrency, modify createCdkDeploymentWorkflows and rerun Projen.

Ready to experiment with feature branches? Continue with Branch-based Development.

← Project StructureEnvironments →