From ca5dae6aff5c173166a4d0db6c96e9fecb246099 Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Wed, 29 Jul 2026 13:00:53 -0400 Subject: [PATCH] docs: align README pinning policy with SHA-pin convention and complete the catalog --- README.md | 46 ++++++++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 01a0484..00ae63e 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ Organization-level GitHub configuration for Sea Haven Industries. **`.github/workflows/ci-static.yaml`** — Reusable CI for static sites (e.g. Eleventy builds for seahaven-site). +**`.github/workflows/ci-mobile-ios.yaml`** — Reusable CI for React Native iOS apps: dependency install, typecheck, optional lint and unit tests, and an unsigned compile (nothing uploaded). Emits the aggregated `ci / ci` status context. + **`.github/workflows/cd-mobile-ios.yaml`** — Reusable CD for iOS apps via Fastlane to TestFlight (Node + Ruby setup inputs). **`.github/workflows/cd-dotnet-eb.yaml`** — Reusable CD for .NET apps on AWS Elastic Beanstalk. Publishes the project, packages a bundle, uploads it, creates an application version, and updates an **existing** environment with OIDC credentials — it never creates an environment. Serialised per environment via a `concurrency` group, and the post-deploy check fails the job if EB rolls the deploy back. The caller owns branch-to-environment mapping. @@ -30,19 +32,31 @@ Organization-level GitHub configuration for Sea Haven Industries. **`.github/workflows/callable-dependency-review.yaml`** — Dependency review on PRs, failing on high severity. Requires Dependency Graph. +**`.github/workflows/release.yaml`** — Reusable release workflow: creates an annotated git tag at a commit and publishes a GitHub Release pointing at it. The version is an input (not read from a manifest). + +**`.github/workflows/release-on-merge.yaml`** — Repo automation (not callable): cuts a tag and GitHub Release for **this** repo whenever a merge to `main` changes a reusable workflow, so Dependabot has a release to advance consumer SHA pins to (see the pinning policy below). + +**`.github/workflows/labeler.yaml`** — This repo's own thin caller of `callable-labeler.yaml`, so the labeler runs on `.github`'s own PRs. + **`.github/workflows/ci.yaml`** — Self-CI for this repo: actionlint (checksum-verified install) over all workflow files, emitting the required `ci / ci` status context. Its shellcheck integration is enabled, so `run:` bodies are shell-linted too; the two deploy steps that rely on intentional word-splitting (`sam deploy … $PARAMS`, `cdk deploy $STACKS`) carry a per-line, commented `# shellcheck disable=SC2086` rather than being quoted or globally exempted. ### Workflow templates (`workflow-templates/`) -Starter workflows offered on the org's **Actions → New workflow** page: `ci-python`, `ci-node`, `cdk-deploy`, `sam-deploy`, `dotnet-eb-deploy`, `dependency-review`, `labeler`, `triage`. Each is a thin caller of the corresponding reusable workflow above (`triage` is standalone). Every template has a paired `properties.json` (name, description, icon, `filePatterns` for auto-suggestion). Replace any `REPLACE-ME` placeholders before enabling. +Starter workflows offered on the org's **Actions → New workflow** page: `cdk-deploy`, `ci-dotnet`, `ci-mobile-ios`, `ci-node`, `ci-python`, `ci-python-app`, `ci-static`, `ci-typescript-frontend`, `dependency-review`, `dotnet-eb-deploy`, `labeler`, `mobile-ios-deploy`, `release`, `sam-deploy`, `triage`. Each is a thin caller of the corresponding reusable workflow above (`triage` is standalone). Every template has a paired `properties.json` (name, description, icon, `filePatterns` for auto-suggestion). Replace any `REPLACE-ME` placeholders before enabling. Templates are not scanned by Dependabot, so refresh their pinned SHAs opportunistically when editing one. -### Action pinning policy +### Ref pinning policy -Third-party action refs across the org follow a tiered policy: +All workflow refs across the org are pinned to full commit SHAs: -- **High-trust / high-blast-radius third-party actions are SHA-pinned** with a trailing version comment (e.g. `actions/labeler` in `callable-labeler.yaml`), and binary installs are checksum-verified (actionlint in `ci.yaml`). Dependabot keeps the SHA current via its trailing-comment mechanism. -- **Common first-party actions** (`actions/checkout`, `actions/dependency-review-action`, `actions/github-script`) are pinned to a **major tag** (`@v7`, `@v5`, …) and kept current by Dependabot version updates gated by CI. -- **Org reusable workflows** are referenced at **`@main`** (`uses: Sea-Haven-Industries/.github/.github/workflows/…@main`). This is deliberate: caller and callable share one trust domain, and pinning callers to a SHA would freeze every consumer against central fixes. Templates in `workflow-templates/` follow the same `@main` convention. +- **Org reusable workflows** are referenced at a **full commit SHA** of this repo with a trailing comment naming the ref or release the pin tracks: + + ```yaml + uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@ # 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. +- **Binary installs are checksum-verified** (actionlint in `ci.yaml`). ### AWS deploy roles & IAM (`oidc-deploy-roles.yaml`) @@ -135,7 +149,7 @@ on: 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@ # ``` **TypeScript CDK repo** (e.g., seahaven-door-unlock-api, seahaven-slack-bot): @@ -148,7 +162,7 @@ on: 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@ # ``` **Node.js SAM repo** (e.g., payments-dashboard): @@ -161,7 +175,7 @@ on: 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@ # with: run-typecheck: false run-cdk-synth: false @@ -178,12 +192,12 @@ on: jobs: python: - uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/ci-python-sam.yaml@ # with: source-dirs: "src" run-sam-validate: false typescript: - uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/ci-typescript-cdk.yaml@ # ``` ### 3. Add CD to a repo @@ -200,7 +214,7 @@ on: jobs: deploy: - uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@ # with: stack-name: afterhours-shift-manager cfn-role-arn: arn:aws:iam::328440206208:role/github-cfn-execution-role @@ -220,7 +234,7 @@ on: jobs: deploy: - uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@ # secrets: deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} ``` @@ -235,7 +249,7 @@ on: jobs: deploy: - uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@ # with: python-version: "3.12" cdk-dir: cdk @@ -253,7 +267,7 @@ on: jobs: deploy: - uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/cd-cdk.yaml@ # with: enable-qemu: true secrets: @@ -270,7 +284,7 @@ on: jobs: deploy: - uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@main + uses: Sea-Haven-Industries/.github/.github/workflows/cd-dotnet-eb.yaml@ # with: project: Api.SeaHavenIndustries/Api.SeaHavenIndustries.csproj eb-application: shoc-backend