Deployment

Each environment has a CD pipeline that synthesizes and deploys the application stack. The pipelines that are already deployed were created with CDK CLI 1.127 and cannot deploy a CDK v2 cloud assembly. Before merging onto a pipeline branch, deploy that pipeline once from a workstation that has CDK CLI 2.1147.0:

$ uv sync --frozen
$ make lambda-reqs
$ export GITHUB_TOKEN="$(gh auth token)"
$ PYB_ENV=development npx --yes aws-cdk@2.1147.0 diff
$ PYB_ENV=development npx --yes aws-cdk@2.1147.0 deploy CD -c branch_name=<branch>
$ PYB_ENV=development npx --yes aws-cdk@2.1147.0 deploy CI

Repeat the CD deploy for staging and production. make lambda-reqs writes the Lambda requirements.txt files that the common-layer Docker build copies, so run it before the first CDK command on a fresh checkout. That Docker build clones pyb-sdk and EventLoggerPySDK from GitHub with GITHUB_TOKEN. make deploy ENV=development deploys every stack in the app (CI, CD, and the application stage). For staging and production, make deploy only deploys CD and requires the pipeline branch, for example make deploy ENV=production BRANCH=release. The pipeline then deploys the application stage. make synth and make deploy stop if PYB_ENV_NAME (from your shell or .env) renames a staging or production stack. Use the deploy CD and deploy CI commands above when only the pipeline or the pull-request project should change.

CD is selected by PYB_ENV in settings.toml (development, staging, production). CI is the CodeBuild project that runs buildspec.yaml on pull requests.

Confirm cdk diff updates the DynamoDB tables, state machines, functions, and rules in place. The CDK app keeps the same construct IDs.

After that first deploy, the pipeline uses the CodeBuild image standard:7.0, Python 3.12, and CDK CLI 2.1147.0. The synth step is:

$ pip install uv
$ git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"
$ uv sync --frozen
$ make lambda-reqs
$ uv run cdk synth CD -c branch_name=$SOURCE_BRANCH_NAME

PYB_ENV and PYB_ENV_NAME are set on that step from settings.toml. GITHUB_TOKEN comes from the Secrets Manager secret aws-codebuild-token. CodeBuild installs aws-cdk@2.1147.0 before those commands, so uv run cdk resolves to that CLI inside the pipeline.

Roll back a bad application deploy by reverting the commit and letting CD deploy again. The assistance table has point-in-time recovery enabled.