docs: Security Suite required-workflow maintenance (SHA-pin the whole tree) by dkastl · Pull Request #91 · geolonia/.github

dkastl · 2026-07-06T00:45:12Z

Writes down the constraint we just learned the hard way, so the next release doesn't re-break the org-wide gate.

The ruleset "require workflows" injector runs the Security Suite only when its entire reusable tree is SHA-pinned; a moving @v1 anywhere makes the required check hang silently at "Expected" on every consumer PR (the v1.27–v1.29 regression, #88/#89/#90).

New docs/workflows/security-suite.md: enforcement model, the SHA-pinning rule (with the tree diagram), the two-release chain-bump release procedure, post-release verification (re-trigger a consumer PR — @v1 moving is not proof), and why geolonia/.github must stay out of the ruleset targets.
Linked from docs/workflows.md (+ an exception callout) and added to the mkdocs nav.
.serena/memories/reusable_workflows.md: adds the suite, a SPECIAL CASE section warning that the generic "move v1 forward" is unsafe for this tree, and a troubleshooting entry for the silent "Expected" hang.

No code changes. No em-dashes.

Summary by CodeRabbit

Documentation
- Added guidance for the new Security Suite workflow, including how it appears in the workflows catalog.
- Documented the required setup for this org-wide security gate, including strict pinning guidance and how updates should be rolled out safely.
- Added troubleshooting notes for cases where the required security check appears stuck or doesn’t complete as expected.

@v1

…the whole tree) Capture the hard-won constraint so the next release doesn't reintroduce the org-wide breakage: the ruleset 'require workflows' injector runs the suite only when its ENTIRE reusable tree is SHA-pinned; a moving @v1 anywhere makes the required check hang silently at 'Expected' on every consumer PR. - New docs/workflows/security-suite.md: enforcement model, the SHA-pinning rule, the two-release chain-bump procedure, post-release verification, and why geolonia/.github must stay out of the ruleset targets. - Link it from docs/workflows.md (+ an exception callout) and mkdocs nav. - .serena/memories/reusable_workflows.md: add the suite, a SPECIAL CASE section (the generic 'move v1 forward' is unsafe here), and a troubleshooting entry.

coderabbitai · 2026-07-06T00:45:19Z

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: d52b652f-9b20-463e-a135-eb50ceb1dae6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Walkthrough

This PR adds documentation for a new "Security Suite" org-wide reusable workflow, including a dedicated doc page, an entry in the workflows index, mkdocs navigation, and maintainer memory notes covering SHA-pinning requirements, a two-release update process, and troubleshooting guidance.

Changes

Security Suite documentation

Layer / File(s)	Summary
New Security Suite documentation page `docs/workflows/security-suite.md`, `mkdocs.yml`	Adds a full doc page describing the four-scanner consolidated gate, ruleset-based enforcement, SHA-pinning requirement across the reusable tree, the two-release update procedure, post-release verification, ruleset exclusions, and troubleshooting; registers the page in mkdocs navigation.
Workflows index update `docs/workflows.md`	Adds Security Suite to the available workflows table and notes an exception requiring immutable SHA pinning at every level to avoid silent required-check hangs.
Maintainer memory notes update `.serena/memories/reusable_workflows.md`	Adds a maintained-workflows bullet for security-suite, a "SPECIAL CASE" section detailing the two-step SHA-pinning release procedure, and a troubleshooting entry for stuck "Expected" checks.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

geolonia/geolonia-operations#196: Documents the same org-wide Security Suite reusable workflow and its SHA-pinning/ruleset-enforcement requirements.

Possibly related PRs

geolonia/.github#79: Bumps the pinned reusable-security-suite ref, directly relating to the documented two-step SHA-pinning release process.
geolonia/.github#86: Changes Security Suite's own reusable references to float on @v1, directly overlapping the documented pinning-safety guidance.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: documenting the Security Suite required-workflow and its SHA-pinning maintenance rule.
Description check	✅ Passed	The description covers the main changes well, though it does not use the template headings or include a Related Issues section.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/security-suite-maintenance

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-07-06T00:45:46Z

🛡️ Security suite

Check	Result
✅ Supply chain · `bumblebee`	No exposure matches
✅ Secrets · `betterleaks`	No secrets in diff
✅ Action pinning · `pinact`	All actions pinned
✅ Actions audit · `zizmor`	No findings

Note

All security checks passed.

_{Updated for ff095b3 · workflow run}

dkastl · 2026-07-06T00:47:13Z

@coderabbitai review

coderabbitai · 2026-07-06T00:47:17Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

dkastl · 2026-07-06T01:14:06Z

Superseded by the float-refs PR: #91 misattributed the outage to floating reusable refs. The real cause was an annotated v1 tag; the corrected docs live in the new PR.

@v1

…l root cause (TODO 1) (#92) The org-wide Security Suite outage (v1.27-v1.31) was NOT caused by floating reusable refs (that was a red herring). Root cause: the `v1` tag became an ANNOTATED tag object (my `git tag -a` releases got copied into v1 by the release workflow), and the ruleset 'require workflows' injector cannot resolve an annotated v1 -> it silently produces no run and the required check hangs at 'Expected' forever. Fixed live by recreating v1 lightweight. This restores the no-treadmill floating setup and guards against recurrence: - security-suite.yml + reusable-security-suite.yml: revert reusable refs to @v1 (floating is fine; the .pinact.yml + zizmor.yml @v1 exemptions cover them). - reusable-release-auto-on-tag.yml: peel moved tags to the commit (git tag -f v1 "$TAG^{commit}") so v1/minor are ALWAYS lightweight, even if a release tag is annotated. - release-auto-on-tag.yml: float the caller on @v1 so it picks up the peel fix. - docs/workflows/security-suite.md (new) + workflows.md callout + mkdocs nav + reusable_workflows Serena memory: document that v1 MUST be lightweight, the single-release upgrade flow, post-release verification, and keep-.github-out- of-targets. Corrects the earlier (wrong) 'SHA-pin the whole tree' guidance. Supersedes #91 (which misattributed the cause to reusable refs).

dkastl marked this pull request as ready for review July 6, 2026 00:47

dkastl mentioned this pull request Jul 6, 2026

fix: float suite refs on @v1 + keep v1 lightweight + document the real root cause #92

Merged

dkastl closed this Jul 6, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Security Suite required-workflow maintenance (SHA-pin the whole tree)#91

docs: Security Suite required-workflow maintenance (SHA-pin the whole tree)#91
dkastl wants to merge 1 commit into
mainfrom
docs/security-suite-maintenance

dkastl commented Jul 6, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 6, 2026 •

edited

Loading

Review skipped

Uh oh!

github-actions Bot commented Jul 6, 2026

Uh oh!

dkastl commented Jul 6, 2026

Uh oh!

coderabbitai Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

dkastl commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

dkastl commented Jul 6, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Uh oh!

github-actions Bot commented Jul 6, 2026

🛡️ Security suite

Uh oh!

dkastl commented Jul 6, 2026

Uh oh!

coderabbitai Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkastl commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

dkastl commented Jul 6, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 6, 2026 •

edited

Loading

coderabbitai Bot commented Jul 6, 2026 •

edited

Loading