engineering-handbook/cicd.md

CI/CD Pipelines

Requirement

Every deployable repo must have a CI/CD pipeline. No manual deploys to production. If it deploys to AWS, it needs a pipeline.

Pipeline Types

SAM / CDK Stacks

Use CodePipeline + CodeBuild, triggered on push to main.

Stage	Action
Source	GitHub connection (push to main)
Build	CodeBuild: sam build && sam package or cdk deploy
Deploy	CloudFormation changeset execute

• Build environment: ARM (aarch64) to match Lambda architecture
• Runtime: Match the project's Lambda runtime (Python 3.12, Node 22.x)
• Pipeline artifacts bucket: {stack-name}-pipeline-artifacts

Frontend / Static Sites

Use CodePipeline or GitHub Actions for build + deploy + cache invalidation.

Stage	Action
Source	GitHub connection (push to main)
Build	Install dependencies, build static assets
Deploy	S3 sync + CloudFront invalidation

Naming

• Pipeline: {stack-name}-pipeline
• CodeBuild project: {stack-name}-build
• Artifacts bucket: {stack-name}-pipeline-artifacts

All kebab-case, matching the stack and repo name.

What the Pipeline Should Do

At minimum:

1. Build — install dependencies, compile/transpile, package
2. Deploy — push to the target environment via CloudFormation or S3

Optionally:

3. Test — run unit/integration tests before deploy
4. Lint — check code style and formatting

When to Add a Pipeline

• When creating a new deployable project — the pipeline is part of the initial setup, not a follow-up
• When working on an existing project that lacks one — flag it and add it as part of the current work

A project is not production-ready without CI/CD.