adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 05:43:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD

Browse source 
- Pin blessed aws-cdk-lib version (2.253.1) with upgrade procedure
- Update Lambda runtime default from Node 22 to Node 24
- Rewrite CI/CD page to reflect GitHub Actions reusable workflows
  (was still referencing CodePipeline/CodeBuild)
This commit is contained in:
Adam Moussa 2026-05-14 18:24:21 -04:00
parent 3bc054c80e
commit bf161add07
2 changed files with 88 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
aws-infrastructure.md
View file

@ -13,13 +13,25 @@ These apply to every Lambda in every project. Verify, don't assume.
| Setting | Value |
|---|---|
| Runtime | Python 3.12 or Node 22.x |
| Runtime | Python 3.12 or Node 24.x |
| Architecture | arm64 |
| Log retention | 60 days (explicit in IaC template) |
| Naming | kebab-case, matching the stack name prefix |
Never rely on the CloudWatch default for log retention. Always set `RetentionInDays` explicitly in the template.
## CDK Version Policy
Pin `aws-cdk-lib` to a known-good version. The current blessed version is **2.253.1**.
Why: aws-cdk-lib bundles transitive dependencies (`inBundle: true`). Certain versions (e.g., 2.254.0) break `npm ci` with phantom missing-package errors. npm `overrides` cannot fix bundled deps. Always test `npm ci` locally before pushing a version bump.
When upgrading, verify on a branch first:
1. Update `package.json` to the new version
2. Run `rm -rf node_modules package-lock.json && npm install`
3. Run `npm ci` — if it fails, the version is not safe
4. Run `npx cdk synth` — if it fails, the version is not safe
## CloudFormation Outputs
Every stack should export:

110
cicd.md
View file

@ -4,51 +4,91 @@
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
## Platform
### SAM / CDK Stacks
GitHub Actions is the standard CI/CD platform. All pipelines use reusable workflows from the `Sea-Haven-Industries/.github` org repo (`.github/workflows/`).
Use CodePipeline + CodeBuild, triggered on push to `main`.
## Workflow Structure
| Stage | Action |
|---|---|
| Source | GitHub connection (push to `main`) |
| Build | CodeBuild: `sam build && sam package` or `cdk deploy` |
| Deploy | CloudFormation changeset execute |
Every repo gets two thin workflow files in `.github/workflows/`:
- 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`
| File | Trigger | Purpose |
|---|---|---|
| `ci.yaml` | `pull_request` on `main` | Lint, typecheck, test, synth/validate |
| `deploy.yaml` | `push` on `main` | Deploy to AWS |
### Frontend / Static Sites
### CDK Stacks (TypeScript)
Use CodePipeline or GitHub Actions for build + deploy + cache invalidation.
```yaml
# .github/workflows/ci.yaml
name: CI
on:
pull_request:
branches: [main]
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main
with:
node-version: "24"
| Stage | Action |
|---|---|
| Source | GitHub connection (push to `main`) |
| Build | Install dependencies, build static assets |
| Deploy | S3 sync + CloudFront invalidation |
# .github/workflows/deploy.yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@main
with:
node-version: "24"
secrets:
deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
```
### SAM Stacks (Python)
```yaml
# .github/workflows/ci.yaml
name: CI
on:
pull_request:
branches: [main]
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@main
# .github/workflows/deploy.yaml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@main
with:
stack-name: "your-stack-name"
secrets:
cfn-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
```
## Authentication
Deploy workflows authenticate to AWS via OIDC (no long-lived credentials). Each repo needs:
1. An IAM role named `githubdeploy-<repo-name>` with:
- OIDC trust policy for `token.actions.githubusercontent.com`
- Subject condition: `repo:Sea-Haven-Industries/<repo>:ref:refs/heads/main`
- Inline policy allowing `sts:AssumeRole` on CDK/SAM bootstrap roles
2. A repo secret `AWS_DEPLOY_ROLE_ARN` containing the role ARN
## Node.js Version
Always pass `node-version: "24"` to reusable workflows. Local dev uses Node 24 / npm 11 which generates lockfileVersion 3. The workflow defaults match this, but be explicit to avoid drift.
## 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
- All workflow files: kebab-case
- Reusable workflow references: `@main` branch
## When to Add a Pipeline