docs: align organization templates with Cursor conventions

Refs: PLAT-62
This commit is contained in:
Adam Moussa 2026-08-03 17:36:56 -04:00
parent b94062bd86
commit d9a8c7fd8f
No known key found for this signature in database
25 changed files with 70 additions and 53 deletions

View file

@ -1,5 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Internal IT support
url: https://seahaven.atlassian.net/jira/software/projects/INFRA
about: For operational issues, file an INFRA Jira ticket instead.
- name: Jira — DEV / PLAT / SEC
url: https://seahaven.atlassian.net/jira
about: File all org work in Jira (DEV, PLAT, or SEC). INFRA is a closed archive. GitHub Issues are active only on shoc-backend, shoc-frontend-new, and open-swe.

View file

@ -15,7 +15,6 @@ assignees: amoussa1229
## AWS / integration impact
- New or changed AWS resources (Lambda, DynamoDB, S3, API Gateway):
- Slack app(s) involved:
- Confluence Architecture Map update needed: yes / no
## Alternatives considered
<!-- Other approaches and why they were rejected. -->

View file

@ -21,6 +21,4 @@ assignees: amoussa1229
<!-- Exact steps to revert: prior stack version, DeletionPolicy considerations, data restore. -->
## Documentation
- [ ] Confluence Architecture Map (id 1540098) update queued
- [ ] README updated in same PR
- [ ] Project memory entry queued

View file

@ -1,8 +1,14 @@
<!--
PR conventions — see engineering-handbook/pull-requests.md
- Title: imperative mood, under 70 chars, describe the change not the ticket (e.g. "Add receipt parser Lambda", not "PROJ-123" or "Bug fix").
- Scope: one logical change per PR. If the title needs an "and", split it.
- Jira: put the issue key in the branch name or this PR title (e.g. [PROJ-123]) to link the PR into the Jira issue's development panel. Omit if the work has no ticket.
PR conventions
- Title format: type(scope): description (DEV-123)
- type ∈ feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, release
- Active Jira projects: DEV (product), PLAT (platform), SEC (security). INFRA is a closed archive.
- The Jira key is required at the end of the title in parentheses.
- Jira-exempt only: Dependabot PRs and permission-controlled emergency reverts.
- Branch: feature/, fix/, hotfix/, chore/, docs/, refactor/, release/ + kebab-case description.
Branch names do not contain Jira keys.
- Scope: one logical change per PR. If the title needs "and", split it.
- Body: state verifiable facts about the change and validation. Do not cite the handbook or add AI-attribution footers.
-->
## Summary
@ -15,13 +21,4 @@ PR conventions — see engineering-handbook/pull-requests.md
<!-- What tests were added, updated, or run. If no automated tests, explain the manual testing. -->
## Notes
<!-- Anything reviewers should know: migration steps, deploy order, follow-ups, breaking changes. Delete this section if empty. -->
## Sea Haven checklist
- [ ] CDK diff / SAM changeset reviewed (if infra change)
- [ ] Secrets added to Parameter Store / Secrets Manager (not hardcoded)
- [ ] DynamoDB PITR verified on new tables
- [ ] Slack notification tested in staging
- [ ] Confluence Architecture Map updated
- [ ] Memory update queued (if new repo/stack)
- [ ] Cross-review requested (if IAM or Lambda handler signature change)
<!-- Anything reviewers should know: migration steps, deploy order, follow-ups, breaking changes. Use None. if empty. -->

View file

@ -4,7 +4,7 @@ name: CD — .NET Elastic Beanstalk
#
# jobs:
# deploy:
# uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@<full-commit-sha> # main
# uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@<full-commit-sha> # v1.0.4
# with:
# project: "Api.Example/Api.Example.csproj"
# eb-application: "example-api"

View file

@ -35,7 +35,7 @@ name: CI — Mobile iOS
# Caller example:
# jobs:
# ci:
# uses: Sea-Haven-Industries/.github/.github/workflows/ci-mobile-ios.yaml@<full-commit-sha> # main
# uses: Sea-Haven-Industries/.github/.github/workflows/ci-mobile-ios.yaml@<full-commit-sha> # v1.0.4
# with:
# working-directory: mobile
# cache-dependency-path: mobile/package-lock.json

View file

@ -15,7 +15,7 @@ name: CI — Static Site
# Caller example (build mode):
# jobs:
# ci:
# uses: Sea-Haven-Industries/.github/.github/workflows/ci-static.yaml@<full-commit-sha> # main
# uses: Sea-Haven-Industries/.github/.github/workflows/ci-static.yaml@<full-commit-sha> # v1.0.4
# with:
# build-command: "npx @11ty/eleventy"
# check-dir: "_site"

View file

@ -13,7 +13,7 @@ name: CI — TypeScript Frontend
# Caller example:
# jobs:
# ci:
# uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-frontend.yaml@<full-commit-sha> # main
# uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-frontend.yaml@<full-commit-sha> # v1.0.4
# with:
# node-version: "24"

View file

@ -32,7 +32,7 @@ name: Release — Tag and GitHub Release
# Caller example:
# jobs:
# release:
# uses: Sea-Haven-Industries/.github/.github/workflows/release.yaml@<full-commit-sha> # main
# uses: Sea-Haven-Industries/.github/.github/workflows/release.yaml@<full-commit-sha> # v1.0.4
# with:
# version: ${{ inputs.version }}
#

View file

@ -2,6 +2,28 @@
Organization-level GitHub configuration for Sea Haven Industries.
## Git and PR conventions
### Branch naming
`feature/`, `fix/`, `hotfix/`, `chore/`, `docs/`, `refactor/`, `release/` + kebab-case description. Branch names do not contain Jira keys.
### Commit format
`type(scope): description` — lowercase, imperative, no trailing period, header ≤ 72 chars. Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`, `release`. Breaking change: `feat!:` + `BREAKING CHANGE:` footer.
### PR title
`type(scope): description (DEV-123)` — the Jira key is required at the end in parentheses. Active projects: **DEV** (product), **PLAT** (platform), **SEC** (security). INFRA is a closed archive. Jira-exempt only: Dependabot PRs and permission-controlled emergency reverts.
### PR body
Exactly four headings in order: `## Summary`, `## Validation`, `## Tests`, `## Notes`. Use `None.` under Notes if empty.
### Deploy path
The two sanctioned deploy paths are merge to `main` triggering the pipeline and `workflow_dispatch` on that same pipeline. No manual workstation deploys to production.
## What's in here
### Reusable Workflows
@ -54,8 +76,8 @@ All workflow refs across the org are pinned to full commit SHAs:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@<full-commit-sha> # v1.0.3
```
Branch refs are mutable: a bad commit on this repo would flow instantly into every consumer's CI and deploy path, while a SHA pin turns the same change into a reviewable Dependabot PR. Two prerequisites keep pins advancing instead of freezing: every consumer repo's `dependabot.yml` must include the `github-actions` ecosystem (weekly), and Dependabot must be granted access to this repo at the org level (Org Settings → Advanced Security → Global settings → "Grant Dependabot access to repositories"); without the grant, update jobs fail with `git_dependencies_not_reachable` and pins freeze silently. `release-on-merge.yaml` tags this repo on every reusable-workflow change so Dependabot has releases to diff against. When adding a caller by hand, pin to the current tip of `main` (`gh api /repos/Sea-Haven-Industries/.github/commits/main --jq .sha`) and let Dependabot advance it from there.
- **Third-party and first-party actions** (`actions/checkout`, `actions/setup-python`, `actions/labeler`, …) are likewise **SHA-pinned** with a trailing version comment (e.g. `actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1`); Dependabot keeps the SHA and comment current.
Branch refs are mutable: a bad commit on this repo would flow instantly into every consumer's CI and deploy path, while a SHA pin turns the same change into a reviewable Dependabot PR. Two prerequisites keep pins advancing instead of freezing: every consumer repo's `dependabot.yml` must include the `github-actions` ecosystem (weekly), and Dependabot must be granted access to this repo at the org level (Org Settings → Advanced Security → Global settings → "Grant Dependabot access to repositories"); without the grant, update jobs fail with `git_dependencies_not_reachable` and pins freeze silently. `release-on-merge.yaml` tags this repo on every reusable-workflow change so Dependabot has releases to diff against. When adding a caller by hand, pin to the latest release commit (`gh api /repos/Sea-Haven-Industries/.github/commits/vX.Y.Z --jq .sha`), annotate it with `# vX.Y.Z`, and let Dependabot advance it from there.
- **Third-party and first-party actions** (`actions/checkout`, `actions/setup-python`, `actions/labeler`, …) — a subset are already SHA-pinned (e.g. `actions/labeler`, `aws-actions/*`, `docker/setup-qemu-action`, `ruby/setup-ruby`); the remainder (`actions/checkout`, `actions/setup-node`, `actions/setup-python`, `actions/setup-dotnet`, `actions/dependency-review-action`) currently use floating major-version tags. Full SHA pinning for this group is deferred (PLAT backlog); Dependabot will keep SHA and comment current once pins are set.
- **Binary installs are checksum-verified** (actionlint in `ci.yaml`).
### AWS deploy roles & IAM (`oidc-deploy-roles.yaml`)
@ -110,7 +132,7 @@ A function's effective permissions are the **intersection** of its own role poli
2. Redeploy the SAM stacks so their roles pick it up (while the exec role still permits it).
3. *Then* tighten the exec role.
Wrong order breaks every SAM deploy. (History: INFRA-103 established the boundary, INFRA-97 scoped the role.) CDK repos are unaffected — they deploy via `cdk-hnb659fds-*` roles, not this execution role.
Wrong order breaks every SAM deploy. CDK repos are unaffected — they deploy via `cdk-hnb659fds-*` roles, not this execution role.
This ordering rule is about changing the **boundary** or the conditions that gate it. It does not apply to changes that only add permissions to the exec role.
@ -149,7 +171,7 @@ on:
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
```
**TypeScript CDK repo** (e.g., seahaven-door-unlock-api, seahaven-slack-bot):
@ -162,7 +184,7 @@ on:
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
```
**Node.js SAM repo** (e.g., payments-dashboard):
@ -175,7 +197,7 @@ on:
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
run-typecheck: false
run-cdk-synth: false
@ -192,12 +214,12 @@ on:
jobs:
python:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
source-dirs: "src"
run-sam-validate: false
typescript:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
```
### 3. Add CD to a repo
@ -214,7 +236,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
stack-name: afterhours-shift-manager
cfn-role-arn: arn:aws:iam::328440206208:role/github-cfn-execution-role
@ -234,7 +256,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
secrets:
deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
```
@ -249,7 +271,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
python-version: "3.12"
cdk-dir: cdk
@ -267,7 +289,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
enable-qemu: true
secrets:
@ -284,7 +306,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@<full-commit-sha> # <release>
uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
project: Api.SeaHavenIndustries/Api.SeaHavenIndustries.csproj
eb-application: shoc-backend

View file

@ -4,7 +4,8 @@ Sea-Haven-Industries repositories are private and intended for internal Sea Have
## Where to go
- **Bugs, feature requests, infrastructure work** — file a ticket in Jira (**INFRA** project) or open an issue on the relevant repository.
- **Bugs and feature requests** — file a ticket in Jira (**DEV**, **PLAT**, or **SEC** depending on scope). GitHub Issues are active only on shoc-backend, shoc-frontend-new, and open-swe (contractor/fork intake).
- **Infrastructure and platform work** — use the **PLAT** project. Security issues go in **SEC**.
- **Operational or urgent issues** — contact Adam Moussa (adam@seahavenind.com).
- **Engineering conventions and standards** — see the [engineering-handbook](https://github.com/Sea-Haven-Industries/engineering-handbook).
- **Security vulnerabilities** — follow [SECURITY.md](SECURITY.md) (do not open a public issue).

View file

@ -5,7 +5,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Matches local dev (Node 24 / npm 11, lockfileVersion 3). This is also the
# reusable workflow's default — passed explicitly to pin against drift.

View file

@ -11,4 +11,4 @@ jobs:
# Every input is optional. Common overrides: `solution` (defaults to *.sln
# in the working directory), `working-directory`, and `dotnet-version`
# (defaults to 8.0.x). This reusable has no `node-version` input.
uses: Sea-Haven-Industries/.github/.github/workflows/ci-dotnet.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-dotnet.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4

View file

@ -7,7 +7,7 @@ jobs:
ci:
# Job id MUST stay `ci`: the reusable's aggregator job is also `ci`, so the
# check context resolves to the required `ci / ci`.
uses: Sea-Haven-Industries/.github/.github/workflows/ci-mobile-ios.yaml@9389e51c10c506caa55f204527452a9e29b0e438 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-mobile-ios.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Matches local dev (Node 24 / npm 11, lockfileVersion 3). This is also
# the reusable workflow's default — passed explicitly to pin against drift.

View file

@ -5,7 +5,7 @@ on:
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Matches local dev (Node 24 / npm 11, lockfileVersion 3). This is also the
# reusable workflow's default — passed explicitly to pin against drift.

View file

@ -11,4 +11,4 @@ jobs:
# Every input is optional. Common overrides: `source-dirs` (ruff targets),
# `requirements` (non-default requirements file), `subproject-dir` (a
# self-contained suite that must run in its own working directory).
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-app.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-app.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4

View file

@ -5,7 +5,7 @@ on:
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
run-tests: true
# ci-python-sam.yaml declares a `node-version` input (default "24") that

View file

@ -7,7 +7,7 @@ jobs:
ci:
# Job id MUST stay `ci`: the reusable's job is also `ci`, so the check
# context resolves to the required `ci / ci`.
uses: Sea-Haven-Industries/.github/.github/workflows/ci-static.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-static.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Pinned explicitly (handbook): local dev is Node 24 / npm 11, which
# generates lockfileVersion 3. Being explicit avoids lockfile drift.

View file

@ -7,7 +7,7 @@ jobs:
ci:
# Job id MUST stay `ci`: the reusable's job is also `ci`, so the check
# context resolves to the required `ci / ci`.
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-frontend.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-frontend.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Pinned explicitly (handbook): local dev is Node 24 / npm 11, which
# generates lockfileVersion 3. Being explicit avoids lockfile drift.

View file

@ -8,4 +8,4 @@ permissions:
jobs:
dependency-review:
uses: Sea-Haven-Industries/.github/.github/workflows/callable-dependency-review.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/callable-dependency-review.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4

View file

@ -5,7 +5,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Required: the project to publish, relative to the repo root.
project: REPLACE-ME-project-csproj

View file

@ -13,4 +13,4 @@ permissions:
jobs:
label:
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4

View file

@ -5,7 +5,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-mobile-ios.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/cd-mobile-ios.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Pinned explicitly (handbook): local dev is Node 24 / npm 11, which
# generates lockfileVersion 3. Being explicit avoids lockfile drift.

View file

@ -13,7 +13,7 @@ permissions:
jobs:
release:
uses: Sea-Haven-Industries/.github/.github/workflows/release.yaml@9389e51c10c506caa55f204527452a9e29b0e438 # main
uses: Sea-Haven-Industries/.github/.github/workflows/release.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
version: ${{ inputs.version }}
# Tags in this org are v-prefixed MAJOR.MINOR.PATCH; "v" is the default

View file

@ -5,7 +5,7 @@ on:
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@555d07c3a240689a81668026787eba089df4c975 # main
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@81cf168170f356d1423d7736f7ce93fd6611ad53 # v1.0.4
with:
# Required: the CloudFormation stack name (kebab-case, matches repo name).
# NOTE: this is a literal placeholder on purpose — starter-workflow variables