From 9676084fd1ab0d470025b7cad0dc755c27862291 Mon Sep 17 00:00:00 2001 From: Vaclav Vancura Date: Tue, 19 May 2026 20:56:08 +0200 Subject: [PATCH] docs(security): document ci action sha pinning and publish provenance Add GitHub Actions pinning guidance to dependency-policy.md (SHA format, job permissions, Renovate vs manual bumps, CI smoke checks). Cross-link from developer-experience-guide and note why npm provenance is not enabled for the local release flow. Co-Authored-By: Claude Opus 4.6 Signed-off-by: Vaclav Vancura --- docs/developer-experience-guide.md | 9 ++++++++- docs/security/dependency-policy.md | 26 ++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/developer-experience-guide.md b/docs/developer-experience-guide.md index 25afcf2..6ef4987 100644 --- a/docs/developer-experience-guide.md +++ b/docs/developer-experience-guide.md @@ -179,6 +179,9 @@ before 6 AM: - Major updates: manual review with `major-update` label - Vulnerability alerts are enabled +CI workflows pin third-party actions by commit SHA (not `@vN` tags). See +[dependency-policy.md](security/dependency-policy.md#github-actions-pinning) for bumping SHAs and job permissions. + ### Declaration tooling (TypeScript / API Extractor) Public `.d.ts` output is produced by `vite-plugin-dts` with `rollupTypes: true`, which runs **API Extractor** during @@ -223,8 +226,12 @@ each build. It fails on known drift-warning patterns and verifies the API Extrac - [ ] Test library build - [ ] Test examples deployment - [ ] Create a GitHub release with notes -- [ ] Publish `blit-tech` to npm (`npm publish --access public`) +- [ ] Publish `blit-tech` to npm (`pnpm release` or `pnpm publish --access public` after `pnpm build`) - [ ] Verify package page and install flow: https://www.npmjs.com/package/blit-tech and `npm install blit-tech` + +npm **provenance** is not enabled: publishing is local-only today. `pnpm publish --provenance` needs an OIDC-backed CI +publish job; see [dependency-policy.md](security/dependency-policy.md#npm-publish-provenance). + - [ ] Announce on socials/discussions ### Quarterly diff --git a/docs/security/dependency-policy.md b/docs/security/dependency-policy.md index a7c1274..6414758 100644 --- a/docs/security/dependency-policy.md +++ b/docs/security/dependency-policy.md @@ -44,6 +44,32 @@ updates require manual review. blocked by release age may be listed in `minimum-release-age-exclude[]` together with `pnpm.overrides` in [`package.json`](../../package.json). Document the reason in the PR that introduces the exclude or override. +## GitHub Actions pinning + +Workflows under [`.github/workflows/`](../../.github/workflows/) pin third-party actions to a **40-character commit +SHA**, with an optional trailing comment for the human-readable tag (for example `actions/checkout@ # v6`). Mutable +`@vN` tags are not used in [`ci.yml`](../../.github/workflows/ci.yml) or +[`pr-checks.yml`](../../.github/workflows/pr-checks.yml). + +Each job declares the **minimum** `permissions` it needs (for example `contents: read` for build-only jobs; the +benchmark job adds `actions: read` and `pull-requests: write` only where artifact lookup and PR comments require it). + +### Bumping pinned actions + +| Path | Who updates SHAs | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| **Routine** | [Renovate](../../renovate.json) `github-actions` manager — grouped PRs, 3-day `minimumReleaseAge`, patch automerge | +| **Manual** | Resolve the release tag commit on the action repo, replace the SHA in the workflow, keep or update the `# vN` comment | + +After any workflow edit, confirm the affected jobs still pass in CI (artifact upload, Codecov, benchmark baseline +lookup, PR benchmark comments). + +### npm publish provenance + +Library releases use the local `pnpm release` script (`pnpm build && pnpm publish`). **npm provenance** +(`pnpm publish --provenance`) expects an OIDC-backed publish environment (typically a dedicated GitHub Actions release +workflow). That flow is not wired today; provenance would be a separate change if releases move into CI. + ## Temporary risk acceptance Do not merge with a failing audit unless the finding is formally accepted: -- 2.51.2