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

Compare commits

base: adam:0e83835b4a03e037e561ff555c8493a857439416
Branches Tags
adam:main
adam:claude/dreamy-mccarthy-1c95cw
adam:fix/auto-merge-concurrency
...
compare: adam:190b683bb3b954c79ff6170f4495948ee0c7f427
Branches Tags
adam:main
adam:claude/dreamy-mccarthy-1c95cw
adam:fix/auto-merge-concurrency

4 commits
0e83835b4a ... 190b683bb3

Author SHA1 Message Date
Adam Moussa
190b683bb3
Merge pull request #19 from Sea-Haven-Industries/ci/sha-pin-workflow-refs
Some checks are pending
ci / ci / ci (push) Waiting to run
Details 
ci: pin reusable-workflow refs to commit SHA
 2026-07-27 15:44:35 -04:00
Adam Moussa
75fb1b0890
ci: pin reusable-workflow refs to commit SHA 
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).
 2026-07-27 15:40:40 -04:00
Adam Moussa
a75623313b
Merge pull request #18 from Sea-Haven-Industries/docs/sha-pin-reusable-workflows 
docs(cicd): pin reusable-workflow refs to commit SHAs instead of @main
 2026-07-27 15:30:25 -04:00
Adam Moussa
5f1818cd6b
docs(cicd): pin reusable-workflow refs to commit SHAs instead of @main 
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).
 2026-07-27 15:28:31 -04:00
3 changed files with 35 additions and 7 deletions
Show stats Expand all files Collapse all files

11
.github/dependabot.yml vendored Normal file
View file

@ -0,0 +1,11 @@
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
groups:
minor-and-patch:
update-types:
- "minor"
- "patch"

2
.github/workflows/labeler.yml vendored
View file

@ -8,4 +8,4 @@ permissions:
issues: write
jobs:
label:
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@main
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@786dcfe8d95af8e640a76b09f30d2c0e86792157 # main

29
cicd.md
View file

@ -27,7 +27,7 @@ on:
branches: [main]
jobs:
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:
node-version: "24"
@ -38,7 +38,7 @@ on:
branches: [main]
jobs:
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:
node-version: "24"
secrets:
@ -55,7 +55,7 @@ on:
branches: [main]
jobs:
ci:
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@main
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@<full-commit-sha> # main
# .github/workflows/deploy.yaml
name: Deploy
@ -64,7 +64,7 @@ on:
branches: [main]
jobs:
deploy:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@main
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@<full-commit-sha> # main
with:
stack-name: "your-stack-name"
secrets:
@ -88,7 +88,24 @@ Always pass `node-version: "24"` to reusable workflows. Local dev uses Node 24 /
## Naming
- All workflow files: kebab-case
- Reusable workflow references: `@main` branch
- Reusable workflow references: pinned to a full 40-character commit SHA with a `# main` comment — never a branch or tag ref
## Workflow Ref Pinning
Reusable workflow references are pinned to a full commit SHA of the central `.github` repo, with a trailing `# main` comment:
```yaml
uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@<full-commit-sha> # main
```
Branch refs are mutable: a compromised or bad commit on the central repo would flow instantly into every consumer's CI and deploy path. A SHA pin turns that same change into a reviewable Dependabot PR instead. The comment tells Dependabot (and readers) which ref the pin tracks.
Per the pinning principle, pins are for reproducibility, not for freezing time. Two prerequisites keep them moving:
1. Every repo's `dependabot.yml` must include the `github-actions` ecosystem (weekly), so pin-advance PRs are opened automatically.
2. Dependabot must be granted access to the internal `.github` 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 — consumers stop receiving central workflow fixes with no visible signal beyond the failed Dependabot run.
When adding a caller workflow by hand, pin to the current tip of the central repo's `main` (`gh api /repos/Sea-Haven-Industries/.github/commits/main --jq .sha`) and let Dependabot advance it from there.
## When to Add a Pipeline
@ -113,7 +130,7 @@ permissions:
issues: write
jobs:
label:
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@main
uses: Sea-Haven-Industries/.github/.github/workflows/callable-labeler.yaml@<full-commit-sha> # main
```
- The trigger is plain `pull_request`, not `pull_request_target`: private repos take no fork PRs, so the lower-privilege event is sufficient and avoids the pwn-request surface. Because `pull_request` runs the workflow from the merge commit, the Labeler check appears on the PR that first adds the caller — an absent or failed check means a missing permission, not expected behaviour.