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 97% rename from docs/workflows.md rename to WORKFLOWS.md index 95a8e05..abc1b83 100644 --- a/docs/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 @@ -557,7 +558,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: