The three pages disagreed: two listed Node 24.x while the workstation
page still allowed 22.x or 24.x, and none said anything about 26.x.
State the rule once under Lambda defaults (24.x standard, 22.x legacy
only until the 2027-04-30 deprecation, never 26.x) and have the other
two pages defer to it.
The CI/CD examples referenced the central reusable workflows at @main,
which contradicts the SHA-pin mandate the CI/CD page states and would be
copied into new repos as a mutable ref. Replace both with the
@<full-commit-sha> # main placeholder and point at the pinning section.
The bin/app.ts example also hardcoded a specific account ID. Make the
env region-only so the account comes from the deploy credentials and the
synthesized template stays account-agnostic.
Pipeline deploy on merge to main (or workflow_dispatch where a repo
configures one) is now the only sanctioned path. Local deploy-then-merge
drops to a documented legacy exception that requires a data-loss-prone
stateful change plus advance sign-off, recorded in the PR notes.
Also correct the hook install path for the repo's move under
repositories/seahaven/, and document that core.hooksPath is a single
directory rather than a search path, so a repo-local setting silently
shadows the machine-global security pre-push unless the repo hook is a
shim that re-execs it.
Adds a Concurrency section to cicd.md covering the blocks that already exist in
the central .github repo:
- Deploy reusables set cancel-in-progress: false; CI reusables set it to true.
- The concurrency block sits on the job, not at workflow top level, and uses
${{ github.job }} in the key where a reusable has more than one job.
- Concurrency groups are evaluated in the caller's repository, so a group only
needs to be unique within one repo; the literal workflow-name prefix is what
keeps two reusables in the same repo apart.
- Deploy keys name the deploy target, so a repo calling one reusable from
several jobs does not serialise independent deploys. cd-cdk keys on `stacks`
rather than `stack-name` for that reason, and every key component is an input
that is required or always defaults.
Quotes the four cd-* group expressions and the ci-typescript-frontend one
verbatim from the workflow files.
The SAM deploy example passed `cfn-role-arn` as a secret and omitted
`deploy-role-arn` entirely. Both are wrong against cd-sam.yaml, which
declares `cfn-role-arn` as a required string INPUT and `deploy-role-arn`
as a required SECRET. A repo scaffolded from the example failed twice:
an unexpected secret, plus a missing required input and secret.
The two ARNs are distinct roles that the old example effectively
conflated into one, so document them side by side: cfn-role-arn is the
CloudFormation execution role the stack deploys as, deploy-role-arn is
the OIDC role the workflow assumes. Also record which inputs have
defaults so callers pass only what they must.
The account ID stays a `<account-id>` placeholder, per the same rule
that removed the hardcoded management-account ARN from the templates.
Pins the labeler caller to the current .github main tip per the SHA-pin
convention (PR #18). Adds dependabot.yml with the github-actions
ecosystem so the pin is advanced weekly; package-ecosystem coverage is
not needed here (no package manifests in this repo).
The org standard for reusable-workflow references changes from the mutable
@main branch ref to full commit SHA pins advanced by Dependabot. Adds a
Workflow Ref Pinning section covering the rationale and the two
prerequisites that keep pins current (github-actions ecosystem in
dependabot.yml, org-level Dependabot access to the internal .github repo).
Make Conventional Commits (type(scope): description) the canonical
commit and PR-title format across Sea Haven, replacing the previous
imperative/capitalized/no-prefix rule.
- commit-messages.md: full rewrite to the type(scope): description
format with the type table, lowercase/imperative description rules,
breaking-change (! + BREAKING CHANGE footer) guidance tied to SemVer,
and updated template and examples.
- git-workflow.md: extend the branch-prefix table with chore/, docs/,
refactor/, and release/ (alongside the existing feature/bug/hotfix),
mirroring the commit types.
- pull-requests.md: reconcile the title rule to the Conventional Commit
format.
- README.md: update the commit-messages one-line summary.
Refs: INFRA-57
Add a standalone ci workflow so handbook changes get an automated gate.
The job is named literally "ci / ci" to emit the exact status context the
org main-branch-protection ruleset requires.
- markdownlint-cli2 (.markdownlint-cli2.jsonc): MD013/MD060/MD040 relaxed
as noisy docs-style rules; fixed 3 MD032 blank-line-around-list issues.
- lychee link check (lychee.toml): internal + external links, tolerates 429.
Codify the org security + merge baseline: auto-merge and auto-delete
head branch (no org default, set per-repo), and the secret-scanning /
CodeQL / code-security surface carried by the 'Sea Haven Standard' org
Code Security Configuration. Note docs-repo CodeQL exception and the
shoc-backend/shoc-frontend-new exclusion.
Capture the org conventions rolled out in the INFRA-47 hygiene pass:
- github-standards.md: static-only README badges (dynamic shields break on
private repos; CI badge is member-only) and a lowercase-hyphenated repo
topic vocabulary, both part of new-repo provisioning.
- cicd.md: the central inline-config reusable PR labeler — pull_request
trigger, the three required caller permissions, no per-repo labeler.yml.
Exact pins remain (reproducibility) but the pinned version is kept
current by Dependabot version updates gated by CI + dependency review,
not by a number frozen in the handbook. Blanket dependabot ignore
entries are banned; version-specific ignores only, commented and
temporary. Bundled-dep vulnerabilities are a prompt to advance the
pin, never to dismiss the alert.
2.253.1 bundles fast-uri 3.1.0 (two high-severity GHSAs, unfixable via
overrides since it ships in the tarball). 2.257.0 bundles patched
fast-uri 3.1.2 and passes npm ci (the 2.254.0 breakage that motivated
the old pin was release-specific).
Pinning every Dependabot PR to a single assignee created noise and a
bottleneck. Remove the assignee requirement and the per-ecosystem
assignees blocks from the example configs.
Both pages existed in working drafts but were not linked from the
README table of contents, so they were undiscoverable. Add them to the
index alongside the related SAM layout and code review pages.
Work is tracked in Jira while code lives in GitHub; the org-level GitHub
for Jira app is already installed but nothing told contributors how to
trigger the link. Document putting the Jira key in the branch name, PR
title, or Refs trailer so branches, commits, and PRs thread into the
issue's development panel. Use a generic PROJ-123 placeholder rather
than naming specific projects, which change over time.
Require PR authors to create a GitHub issue for any review
finding deferred past the current PR, and link it in the
review thread before merging. Prevents informal tracking
from dropping items.
Adds three handbook pages covering conventions that were previously
scattered across feedback memories or rederived from scratch each
time:
- bedrock.md captures the cross-region inference profile requirement
for Claude 4.x Bedrock Agents and the alias-version pinning gotcha,
plus the IAM resource pattern and the KB Docker requirement.
- dev-environment.md documents the workstation directory layout,
pyenv/Node conventions, the macOS launchd/TCC sandbox gotcha, and
cleanup cadence.
- lambda-template.md provides a minimal SAM scaffold that follows the
Lambda defaults already in aws-infrastructure.md (Python 3.12,
arm64, explicit 60-day log retention, scoped Secrets Manager
access, module-level secret cache).
Also extends two existing pages:
- sam-project-layout.md gains a Lambda Layers section with the
BuildMethod nesting pattern that caused a ~22-hour production
outage when violated.
- naming-conventions.md adds a Legacy Stacks note acknowledging that
pre-convention PascalCase stacks (SeaHavenDoorUnlockStack,
WorkorderIngestStack) stay as-is rather than risk stack
replacement.
* 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)
* Add pre-push hook for npm ci validation
Catches lock file drift locally before it breaks CI. Includes
install instructions in git-workflow.md.
* Add repo provisioning script
Automates the new-repo checklist: GitHub repo creation, OIDC deploy
role, repo secret, security features, CI/CD workflow stubs, and
pre-push hook installation. Supports both SAM and CDK stack types.
* Add shared VpnEc2Instance CDK construct
Reference construct for the VPN-accessible EC2 pattern used by
file-share and forgejo. Includes VPC/subnet lookup, SG, IAM role,
encrypted EBS, and DLM snapshots. Copy into lib/constructs/.
* Add post-deploy health check template
Template script for project-specific health checks. Copy to
scripts/health-check.sh — CD workflows run it automatically.
Documents the org-wide policy for dependabot.yml files: ecosystem
selection, standard templates for single/multi-ecosystem repos and
SAM projects, auto-assignment, and merge guidance.
