From 563d7fca7bf23ea297f8e20075ff228a97cc28ed Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 18 Sep 2026 11:19:46 -0400 Subject: [PATCH 1/3] Add zizmor workflow security analysis Runs zizmor (pedantic persona) over the repo's workflows through the OpenTelemetry shared workflow, pinned at v0.13.0, on PRs, main pushes, weekly and on dispatch; results upload to the Security tab. Documents the integration under the CONTRIBUTING maintainer notes. --- .github/workflows/zizmor.yaml | 24 ++++++++++++++++++++++++ CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 .github/workflows/zizmor.yaml diff --git a/.github/workflows/zizmor.yaml b/.github/workflows/zizmor.yaml new file mode 100644 index 0000000000..d444d6c6b7 --- /dev/null +++ b/.github/workflows/zizmor.yaml @@ -0,0 +1,24 @@ +# Workflow security analysis with zizmor, through the OpenTelemetry shared +# workflow, which pins the scanner image by digest. Findings land in the +# Security tab as code-scanning alerts; the job passes regardless, so what +# blocks a merge (if anything) is the branch ruleset. Maintainer notes: +# CONTRIBUTING.md#workflow-security-analysis + +name: zizmor + +on: + push: + branches: [main] + pull_request: + schedule: + - cron: '45 9 * * 5' # weekly: refreshes the online audits' advisory data + workflow_dispatch: +permissions: {} + +jobs: + zizmor: + permissions: + contents: read + security-events: write # SARIF upload to code scanning + uses: open-telemetry/shared-workflows/.github/workflows/zizmor.yml@03559ef555db0eae5d85c3c6347d1530243e7aa7 # v0.13.0 + with: { persona: pedantic } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b80343927..e91cbf2bb7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -113,10 +113,39 @@ npm run local -- serve The `local` prefix runs the script against the sibling Docsy, and the server watches it, so theme edits hot-reload. +### Workflow security analysis + +`.github/workflows/zizmor.yaml` runs [zizmor][] over this repo's workflows in +its pedantic persona (security audits plus workflow hygiene) on every PR, on +pushes to `main`, and weekly, uploading the results to the repository's Security +tab as code-scanning alerts. The weekly run refreshes the online audits, which +check pinned actions against published advisories. + +- The job passes whatever it finds: findings are alerts to triage, not a merge + gate. Blocking, if any, is a repository-settings decision (a code-scanning + rule in the `main` ruleset), not something this workflow does. +- The workflow calls the [OpenTelemetry shared workflow][otel-zizmor] at a + pinned commit; that workflow pins the zizmor action, which pins the zizmor + image by digest, so the scanner moves only when the pin here does. Bump it + like any other action pin: review the chain and honor the release cooldown. +- CI-only by design: the repo carries no tooling dependency for it. For a + comparable local run, with `GH_TOKEN` set for the online audits, where + _`VERSION`_ is the zizmor release the shared workflow currently pins: + + ```bash + uvx zizmor@VERSION --persona=pedantic .github/workflows + ``` + +- `security-events: write` sits alone in this workflow, away from the job that + installs and builds. + [alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys [deploys]: https://app.netlify.com/sites/docsy-example/deploys [Docsy]: https://github.com/google/docsy [hugo-extended]: https://www.npmjs.com/package/hugo-extended [Hugo workspace]: https://gohugo.io/configuration/module/#top-level-settings +[otel-zizmor]: + https://github.com/open-telemetry/shared-workflows/blob/main/zizmor/README.md +[zizmor]: https://docs.zizmor.sh/ From bcb576f065417de4cc6e69b5f9dcca6583386407 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 18 Sep 2026 19:58:07 -0400 Subject: [PATCH 2/3] Lean the zizmor docs Ports the docsy#2811 review outcomes: the workflow header keeps a purpose line and the link; the CONTRIBUTING note states the reporting limit once, folds the bump guidance into the chain sentence, and points the local-run VERSION at what the workflow actually ran. --- .github/workflows/zizmor.yaml | 5 +---- CONTRIBUTING.md | 21 ++++++++++----------- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/.github/workflows/zizmor.yaml b/.github/workflows/zizmor.yaml index d444d6c6b7..f41825cb00 100644 --- a/.github/workflows/zizmor.yaml +++ b/.github/workflows/zizmor.yaml @@ -1,7 +1,4 @@ -# Workflow security analysis with zizmor, through the OpenTelemetry shared -# workflow, which pins the scanner image by digest. Findings land in the -# Security tab as code-scanning alerts; the job passes regardless, so what -# blocks a merge (if anything) is the branch ruleset. Maintainer notes: +# Workflow security analysis with zizmor. Maintainer notes: # CONTRIBUTING.md#workflow-security-analysis name: zizmor diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e91cbf2bb7..0f9a26affe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -117,20 +117,19 @@ watches it, so theme edits hot-reload. `.github/workflows/zizmor.yaml` runs [zizmor][] over this repo's workflows in its pedantic persona (security audits plus workflow hygiene) on every PR, on -pushes to `main`, and weekly, uploading the results to the repository's Security -tab as code-scanning alerts. The weekly run refreshes the online audits, which -check pinned actions against published advisories. +pushes to `main`, and weekly, so the online audits catch advisories published +against already-pinned actions. Results upload to the repository's Security tab +as code-scanning alerts. -- The job passes whatever it finds: findings are alerts to triage, not a merge - gate. Blocking, if any, is a repository-settings decision (a code-scanning - rule in the `main` ruleset), not something this workflow does. +- The job passes whatever it finds; findings are alerts to triage. Blocking, if + any, comes from a code-scanning rule in a ruleset on `main`. - The workflow calls the [OpenTelemetry shared workflow][otel-zizmor] at a pinned commit; that workflow pins the zizmor action, which pins the zizmor - image by digest, so the scanner moves only when the pin here does. Bump it - like any other action pin: review the chain and honor the release cooldown. -- CI-only by design: the repo carries no tooling dependency for it. For a - comparable local run, with `GH_TOKEN` set for the online audits, where - _`VERSION`_ is the zizmor release the shared workflow currently pins: + image by digest, so the scanner moves only when the pin here does. Review the + chain at each bump. +- CI-only by design: the repo carries no tooling dependency for it. For a local + run, with `GH_TOKEN` set for the online audits, where _`VERSION`_ is the + zizmor version the workflow's latest run logs (its `zizmor vX.Y.Z` banner): ```bash uvx zizmor@VERSION --persona=pedantic .github/workflows From a5aa6e85cf53191acc63e2fa7dd5308aa8bb171d Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 18 Sep 2026 20:11:41 -0400 Subject: [PATCH 3/3] Make the blocking sentence conditional; scan `.` locally like CI Review round 1 (r1.1, r1.2). --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f9a26affe..5e7ea36d0e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -122,7 +122,7 @@ against already-pinned actions. Results upload to the repository's Security tab as code-scanning alerts. - The job passes whatever it finds; findings are alerts to triage. Blocking, if - any, comes from a code-scanning rule in a ruleset on `main`. + any, would come from a code-scanning rule in a ruleset on `main`. - The workflow calls the [OpenTelemetry shared workflow][otel-zizmor] at a pinned commit; that workflow pins the zizmor action, which pins the zizmor image by digest, so the scanner moves only when the pin here does. Review the @@ -132,7 +132,7 @@ as code-scanning alerts. zizmor version the workflow's latest run logs (its `zizmor vX.Y.Z` banner): ```bash - uvx zizmor@VERSION --persona=pedantic .github/workflows + uvx zizmor@VERSION --persona=pedantic . ``` - `security-events: write` sits alone in this workflow, away from the job that