diff --git a/cicd.md b/cicd.md index 0d746ec..ed77d2b 100644 --- a/cicd.md +++ b/cicd.md @@ -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@ # 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@ # 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@ # 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@ # 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@ # 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@ # 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.