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

docs(cdk-layout): pin example workflow refs, drop hardcoded account

Browse source 
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.
This commit is contained in:
Adam Moussa 2026-07-28 19:42:47 -04:00
parent cfb50ff1fc
commit fc0e9bdc93
No known key found for this signature in database
1 changed files with 8 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
cdk-project-layout.md
View file

@ -49,10 +49,12 @@ import { ProjectNameStack } from '../lib/project-name-stack';
const app = new cdk.App(); const app = new cdk.App();
new ProjectNameStack(app, 'ProjectNameStack', { new ProjectNameStack(app, 'ProjectNameStack', {
stackName: 'project-name', stackName: 'project-name',
env: { account: '328440206208', region: 'us-east-1' }, env: { region: 'us-east-1' },
}); });
``` ```
Set `region` only. The account comes from the credentials the deploy runs with (the repo's OIDC deploy role), so leaving it unset keeps one entry point working across accounts and keeps the synthesized template account-agnostic. Hard-coding an account ID also literalizes `AWS::AccountId` in the template, which turns unrelated resources into replacement candidates on the next diff.
### `lib/project-name-stack.ts` ### `lib/project-name-stack.ts`
All resource definitions. For larger projects, split into multiple constructs under `lib/` and compose them in the stack file. Keep the stack class thin -- it wires constructs together, not defines low-level resources. All resource definitions. For larger projects, split into multiple constructs under `lib/` and compose them in the stack file. Keep the stack class thin -- it wires constructs together, not defines low-level resources.
@ -141,7 +143,7 @@ Same defaults as SAM projects. Verify these on every Lambda in every CDK stack:
| Setting | Value | | Setting | Value |
|---|---| |---|---|
| Runtime | Python 3.12 or Node 24.x | | Runtime | Python 3.12 or Node 24.x (`nodejs24.x`) |
| Architecture | arm64 | | Architecture | arm64 |
| Log retention | 60 days (explicit `RetentionInDays`) | | Log retention | 60 days (explicit `RetentionInDays`) |
| Naming | kebab-case, prefixed with stack name | | Naming | kebab-case, prefixed with stack name |
@ -155,7 +157,7 @@ new logs.LogGroup(this, 'HandlerLogs', {
}); });
``` ```
See [aws-infrastructure.md](aws-infrastructure.md#lambda-defaults). See [aws-infrastructure.md](aws-infrastructure.md#lambda-defaults), and [Node runtime](aws-infrastructure.md#node-runtime) for the canonical rule on `nodejs24.x` versus the `nodejs22.x` legacy case.
## CI/CD ## CI/CD
@ -171,7 +173,7 @@ on:
branches: [main] branches: [main]
jobs: jobs:
ci: ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@<full-commit-sha> # main
with: with:
node-version: "24" node-version: "24"
@ -182,14 +184,14 @@ on:
branches: [main] branches: [main]
jobs: jobs:
deploy: deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@main uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@<full-commit-sha> # main
with: with:
node-version: "24" node-version: "24"
secrets: secrets:
deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
``` ```
Always pass `node-version: "24"` explicitly. See [cicd.md](cicd.md) for the full pipeline convention. Always pass `node-version: "24"` explicitly. Reusable workflow refs are pinned to a full 40-character commit SHA of the central `.github` repo with a trailing `# main` comment, never to a branch or tag; see [Workflow Ref Pinning](cicd.md#workflow-ref-pinning). Pin to the current tip of that repo's `main` when adding a caller by hand and let Dependabot advance it. See [cicd.md](cicd.md) for the full pipeline convention.
## Bedrock Agents ## Bedrock Agents