From 179bcd80362c750e61e0da323af6e1cbe726495f Mon Sep 17 00:00:00 2001 From: Leonard O'Sullivan Date: Fri, 1 May 2026 13:52:38 +1000 Subject: [PATCH 1/2] docs: move security and workflows docs to repo root These are internal project docs, not user-facing module documentation. Move them out of docs/ (and off GitHub Pages) to the repo root as SECURITY.md and WORKFLOWS.md. Also fixes can_approve_pull_request_reviews documentation to reflect that it must be enabled for release-please and nat-images PR creation. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/security.md => SECURITY.md | 0 docs/workflows.md => WORKFLOWS.md | 2 +- mkdocs.yml | 1 - 3 files changed, 1 insertion(+), 2 deletions(-) rename docs/security.md => SECURITY.md (100%) rename docs/workflows.md => WORKFLOWS.md (98%) diff --git a/docs/security.md b/SECURITY.md similarity index 100% rename from docs/security.md rename to SECURITY.md diff --git a/docs/workflows.md b/WORKFLOWS.md similarity index 98% rename from docs/workflows.md rename to WORKFLOWS.md index 95a8e05..9d33c65 100644 --- a/docs/workflows.md +++ b/WORKFLOWS.md @@ -557,7 +557,7 @@ Repo-level Actions settings that back the workflow security model: - **Allowed actions**: the `selected` allowlist permits only GitHub-owned actions plus the publisher patterns `hashicorp/*`, `aws-actions/*`, `googleapis/*`, `pre-commit/*`, and `astral-sh/*`. Any new third-party action outside these patterns is blocked at run time. - **SHA-pinned references** (convention): every `uses:` reference in this repo's workflow files pins to a full-length commit SHA (e.g. `actions/checkout@34e114...f8d5 # v4`). This closes the "supply-chain tag moves" attack where an upstream action author silently retags to malicious code. The repo-wide `sha_pinning_required` enforcement setting is **not** enabled — it rejects transitive action references inside composite actions (e.g. `pre-commit/action` uses `actions/cache@v4` internally, and the enforcement check blocks the whole workflow). Pinning is maintained by convention, not by the repo-level toggle. - **Default workflow permissions**: `read` — any workflow that needs write permissions must declare them explicitly at the workflow or job level. -- **`can_approve_pull_request_reviews: false`** for the default `GITHUB_TOKEN`: workflows cannot approve PRs via the token. This prevents a compromised or malicious workflow from self-approving. +- **`can_approve_pull_request_reviews: true`** for the default `GITHUB_TOKEN`: workflows can create and approve PRs. This is required by release-please (creates release PRs) and `nat-images.yml` (creates promotion PRs). The setting controls both creation and approval despite the name. Code owner review requirements prevent self-approval from satisfying merge gates. ### Merge decision flow diff --git a/mkdocs.yml b/mkdocs.yml index 5e50e0b..eeb6a40 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,7 +53,6 @@ nav: - Examples: examples.md - Terraform Reference: reference.md - Testing: testing.md - - CI/CD Workflows: workflows.md extra: social: From f59e441a042d310a6cb52594cf7f6a1ad3adc5d4 Mon Sep 17 00:00:00 2001 From: Leonard O'Sullivan Date: Fri, 1 May 2026 13:55:44 +1000 Subject: [PATCH 2/2] docs: document why tag creation rule cannot be enabled The GITHUB_TOKEN used by release-please does not have the Admin repository role, so a creation rule on tags blocks it even with the admin bypass configured. Tag immutability (no delete, no update) is still enforced. Co-Authored-By: Claude Opus 4.6 (1M context) --- WORKFLOWS.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/WORKFLOWS.md b/WORKFLOWS.md index 9d33c65..abc1b83 100644 --- a/WORKFLOWS.md +++ b/WORKFLOWS.md @@ -546,9 +546,10 @@ flowchart LR ### `tags` ruleset -- Protects `refs/tags/v*` — no creation, deletion, or update of version tags. -- Ensures only admins can create version tags (via release-please or manually) and that existing tags are immutable. -- Admin role has `bypass_mode: always` (needed for release-please tag creation and emergency tag management). +- Protects `refs/tags/v*` — no deletion or update of version tags. +- Ensures release-please's tags are immutable once created. +- Tag **creation** is intentionally unrestricted. Release-please creates tags via the GitHub API using the `GITHUB_TOKEN`, which does not have an admin repository role — a `creation` rule would block it even with the admin bypass, because the bypass only applies to actors with the Admin role, not to the `GITHUB_TOKEN` used by workflows. +- Admin role has `bypass_mode: always` (needed for emergency tag management). ### Actions permissions