fix: float suite refs on @v1 + keep v1 lightweight + document the real root cause by dkastl · Pull Request #92 · geolonia/.github

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

Restores the no-treadmill floating setup now that we know the real cause of the org-wide Security Suite outage (v1.27–v1.31), and guards against recurrence + documents it.

Root cause (corrected)

The outage was not the floating reusable refs (that was a red herring the SHA-pinning "fixed" without fixing). 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 can't resolve an annotated v1, so it silently produces no run and the required check hangs at "Expected" forever on every consumer PR. Fixed live by recreating v1 lightweight (the suite immediately injected on infra-cdk#151).

Changes

Revert reusable refs to @v1 in security-suite.yml + reusable-security-suite.yml (floating is fine; .pinact.yml/zizmor.yml @v1 exemptions cover them). → single-release upgrades again, no chain-bump.
reusable-release-auto-on-tag.yml: peel to commit (git tag -f v1 "$TAG^{commit}") so moved v1/minor tags are always lightweight, even if a release tag is annotated. Durable guard against recurrence.
release-auto-on-tag.yml: float the caller on @v1 so it picks up the peel fix.
Docs + memory: new docs/workflows/security-suite.md (the v1-must-be-lightweight rule, single-release flow, post-release verification, keep-.github-out-of-targets), a workflows.md callout, mkdocs nav, and the reusable_workflows Serena memory. Corrects the earlier wrong "SHA-pin the whole tree" guidance.

Supersedes #91

#91 documented the wrong cause; closing it in favor of this.

After merge

Cut v1.32.0 (lightweight tag!) → confirm v1 stays lightweight and the suite still injects on a consumer PR.

Validation: pinact --check exit 0, zizmor clean, no em-dashes.

Summary by CodeRabbit

Bug Fixes
- Updated release and security workflows to use a lightweight floating v1 reference, helping required checks run reliably and avoiding stuck statuses.
- Improved tag handling so release tags resolve consistently during updates.
Documentation
- Added and expanded documentation for the Security Suite workflow, including setup, verification, troubleshooting, and release guidance.
- Updated workflow docs navigation and notes about the new Security Suite entry.

@v1

…l root cause (TODO 1) 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).

coderabbitai · 2026-07-06T01:14:11Z

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: a78fe6ee-e0a8-4c0e-891d-893e5b6d2b18

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 migrates several GitHub Actions workflows from pinned commit SHAs to floating @v1 tag references for reusable workflows, updates release tag-moving logic to peel tags to their commit (ensuring lightweight tags), and adds/updates documentation explaining the v1 lightweight-tag requirement and related troubleshooting.

Changes

Float on v1 and lightweight tag enforcement

Layer / File(s)	Summary
Release workflow tag peeling and consumer `.github/workflows/release-auto-on-tag.yml`, `.github/workflows/reusable-release-auto-on-tag.yml`	The release-auto-on-tag workflow now floats on `@v1`; MINOR/MAJOR tag updates in the reusable workflow peel the release tag to its commit (`$TAG^{commit}`) so moved tags remain lightweight.
Security suite workflows float on v1 `.github/workflows/security-suite.yml`, `.github/workflows/reusable-security-suite.yml`	The suite job and sibling scanner jobs (supply-chain, secret-leak, action-pinning) switch `uses:` references from pinned SHAs to `@v1`, with updated inline comments on the lightweight-tag requirement.
Documentation for Security Suite and lightweight tag rules `docs/workflows/security-suite.md`, `docs/workflows.md`, `.serena/memories/reusable_workflows.md`, `mkdocs.yml`	A new Security Suite doc page, updated workflows.md entry/gotcha, a CRITICAL section and troubleshooting entry in the memory doc, and a new mkdocs navigation entry are added, all explaining the lightweight-`v1` requirement and failure modes.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

geolonia/.github#79: Both PRs modify the suite job's uses: reference for reusable-security-suite.yml, overlapping in workflow call-chain behavior.
geolonia/.github#84: Both PRs change the same security-suite.yml uses: ref to different versions/tags of the reusable security suite workflow.
geolonia/.github#86: Both PRs move security-suite.yml and reusable-security-suite.yml reusable references to float on @v1 with matching documentation updates.

Suggested labels: dependencies, github_actions

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly reflects the main change: floating suite refs, keeping v1 lightweight, and documenting the root cause.
Description check	✅ Passed	The description covers the root cause, changes, follow-up, and validation, so it is mostly complete despite not using the exact template headings.
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 fix/float-refs-and-lightweight-v1

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

github-actions · 2026-07-06T01:14:34Z

🛡️ 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 124044f · workflow run}

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

@coderabbitai review

coderabbitai · 2026-07-06T01:14:52Z

✅ 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.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/workflows/security-suite.md`:
- Around line 17-19: The fenced code block in the security-suite workflow
reference is missing a language identifier, triggering the MD040 markdown lint
rule. Update the fenced block in the documentation so it uses an explicit
language tag, using the existing workflow path text inside the block and keeping
the content unchanged. Locate the block by the workflow reference string in the
documentation and add the appropriate fence label to make the snippet valid
markdown.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4ccc9c81-233f-4099-ae56-7a53c2c611d0

📥 Commits

Reviewing files that changed from the base of the PR and between e247b95 and 124044f.

📒 Files selected for processing (8)

.github/workflows/release-auto-on-tag.yml
.github/workflows/reusable-release-auto-on-tag.yml
.github/workflows/reusable-security-suite.yml
.github/workflows/security-suite.yml
.serena/memories/reusable_workflows.md
docs/workflows.md
docs/workflows/security-suite.md
mkdocs.yml

dkastl marked this pull request as ready for review July 6, 2026 01:14

coderabbitai Bot reviewed Jul 6, 2026

View reviewed changes

Comment thread docs/workflows/security-suite.md

dkastl merged commit bc7186f into main Jul 6, 2026
6 checks passed

dkastl deleted the fix/float-refs-and-lightweight-v1 branch July 6, 2026 01:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

fix: float suite refs on @v1 + keep v1 lightweight + document the real root cause#92
dkastl merged 1 commit into
mainfrom
fix/float-refs-and-lightweight-v1

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!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

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!

Root cause (corrected)

Changes

Supersedes #91

After merge

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!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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