From 3bc054c80e58466b5cbdb88f4e15b7df474b7c22 Mon Sep 17 00:00:00 2001
From: Adam Moussa <166072409+amoussa1229@users.noreply.github.com>
Date: Fri, 8 May 2026 13:56:25 -0400
Subject: [PATCH] Add CI/CD pipeline requirements page (#5)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every deployable repo must have a pipeline — no manual
deploys to production.
---
 README.md |  1 +
 cicd.md   | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+)
 create mode 100644 cicd.md

diff --git a/README.md b/README.md
index 51a66bc..1a48ee4 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ Engineering conventions and best practices for Sea Haven Industries.
 - [AWS Infrastructure](aws-infrastructure.md) -- SAM vs CDK, Lambda defaults, CloudFormation
 - [SAM Project Layout](sam-project-layout.md) -- standard directory structure for serverless projects
 - [Secrets and Configuration](secrets-and-config.md) -- Secrets Manager vs SSM Parameter Store
+- [CI/CD Pipelines](cicd.md) -- every deployable repo gets a pipeline, no manual deploys
 
 ## Contributing
 
diff --git a/cicd.md b/cicd.md
new file mode 100644
index 0000000..b8f5cc8
--- /dev/null
+++ b/cicd.md
@@ -0,0 +1,58 @@
+# 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.