From bf161add07cefeb358a5b68d3f3d76094adb3c88 Mon Sep 17 00:00:00 2001 From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com> Date: Thu, 14 May 2026 18:24:21 -0400 Subject: [PATCH] Update CDK version policy, Node 24 runtime, and GitHub Actions CI/CD - 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) --- aws-infrastructure.md | 14 +++++- cicd.md | 110 ++++++++++++++++++++++++++++-------------- 2 files changed, 88 insertions(+), 36 deletions(-) diff --git a/aws-infrastructure.md b/aws-infrastructure.md index c6f8acf..e63c734 100644 --- a/aws-infrastructure.md +++ b/aws-infrastructure.md @@ -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: diff --git a/cicd.md b/cicd.md index b8f5cc8..176a6ba 100644 --- a/cicd.md +++ b/cicd.md @@ -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-` with: + - OIDC trust policy for `token.actions.githubusercontent.com` + - Subject condition: `repo:Sea-Haven-Industries/: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