diff --git a/AGENTS.md b/AGENTS.md index 8ed3a4e..9746fdf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -250,6 +250,7 @@ Use these rules to keep the trait/factory architecture stable under growth. - Include threat/risk notes and rollback strategy. - Add/update tests or validation evidence for failure modes and boundaries. - Keep observability useful but non-sensitive. +- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change. ## 8) Validation Matrix @@ -378,6 +379,7 @@ Reference docs: - `docs/pr-workflow.md` - `docs/reviewer-playbook.md` - `docs/ci-map.md` +- `docs/actions-source-policy.md` ## 10) Anti-Patterns (Do Not) diff --git a/docs/actions-source-policy.md b/docs/actions-source-policy.md new file mode 100644 index 0000000..baad677 --- /dev/null +++ b/docs/actions-source-policy.md @@ -0,0 +1,62 @@ +# Actions Source Policy (Phase 1) + +This document defines the current GitHub Actions source-control policy for this repository. + +Phase 1 objective: lock down action sources with minimal disruption, before full SHA pinning. + +## Current Policy + +- Repository Actions permissions: enabled +- Allowed actions mode: selected +- SHA pinning required: false (deferred to Phase 2) + +Selected allowlist patterns: + +- `actions/*` (covers `actions/cache`, `actions/checkout`, `actions/upload-artifact`, `actions/download-artifact`, and other first-party actions) +- `docker/*` +- `dtolnay/rust-toolchain@*` +- `Swatinem/rust-cache@*` +- `DavidAnson/markdownlint-cli2-action@*` +- `lycheeverse/lychee-action@*` +- `EmbarkStudios/cargo-deny-action@*` +- `rhysd/actionlint@*` +- `softprops/action-gh-release@*` + +## Why This Phase + +- Reduces supply-chain risk from unreviewed marketplace actions. +- Preserves current CI/CD functionality with low migration overhead. +- Prepares for Phase 2 full SHA pinning without blocking active development. + +## Agentic Workflow Guardrails + +Because this repository has high agent-authored change volume: + +- Any PR that adds or changes `uses:` action sources must include an allowlist impact note. +- New third-party actions require explicit maintainer review before allowlisting. +- Expand allowlist only for verified missing actions; avoid broad wildcard exceptions. +- Keep rollback instructions in the PR description for Actions policy changes. + +## Validation Checklist + +After allowlist changes, validate: + +1. `CI` +2. `Docker` +3. `Security Audit` +4. `Workflow Sanity` +5. `Release` (when safe to run) + +Failure mode to watch for: + +- `action is not allowed by policy` + +If encountered, add only the specific trusted missing action, rerun, and document why. + +## Rollback + +Emergency unblock path: + +1. Temporarily set Actions policy back to `all`. +2. Restore selected allowlist after identifying missing entries. +3. Record incident and final allowlist delta. diff --git a/docs/ci-map.md b/docs/ci-map.md index 3b4a7bc..ac3d192 100644 --- a/docs/ci-map.md +++ b/docs/ci-map.md @@ -76,6 +76,7 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u - Keep merge-blocking checks deterministic and reproducible (`--locked` where applicable). - Prefer explicit workflow permissions (least privilege). +- Keep Actions source policy restricted to approved allowlist patterns (see `docs/actions-source-policy.md`). - Use path filters for expensive workflows when practical. - Keep docs quality checks low-noise (`markdownlint` + offline link checks). - Keep dependency update volume controlled (grouping + PR limits).