feat: keep highest stable semver as GitHub Latest on release (closes #389)

[bedatty]

GitHub Actions Shared Workflows

---

Description

release.yml's Semantic Release step uses @semantic-release/github, which creates the GitHub release without specifying make_latest. The REST API defaults make_latest to true, so every freshly created release becomes "Latest" regardless of semver ordering. A maintenance-line patch (e.g. v1.6.1 from maintenance/1.6.x) published after a higher main-line release (v1.7.0) therefore steals the "Latest" badge and has to be reverted by hand.

This PR adds a post-release job, enforce_latest, that re-asserts "Latest" to the highest stable semver release in the repo. It is the option-(a) approach from #389: idempotent, correct for any single-app repo, and requires no new input and no change in any consumer.

• Runs only when a release was actually published, gated on the existing aggregated output needs.publish_release_status.outputs.release_published == 'true' — so it never runs (and never fails the workflow) when no release was cut.
• Safe under the matrix (monorepo) flow: the job runs once, after the matrix completes, not per-leg.
• || true guards the pipeline so an empty match (no stable vX.Y.Z release — e.g. a monorepo using app-prefixed tags, or a pre-1.0 repo) is a clean no-op instead of a pipefail/set -e abort.
• Main-line behavior is preserved: when the highest stable semver is the version just released, gh release edit --latest is a no-op.
• Added to the notify job's needs and failed_jobs so a failure surfaces in the Slack summary.

Permissions: the job declares contents: write (top-level workflow stays contents: read) and uses github.token.

Type of Change

• feat: New workflow or new input/output/step in an existing workflow

Breaking Changes

None. No inputs/outputs/secrets added or changed; existing callers are unaffected.

Testing

• YAML syntax validated locally (yaml.safe_load)
• Triggered a real workflow run on a caller repository using @this-branch or the beta tag
• Verified all existing inputs still work with default values (no signature change)
• Confirmed no secrets or tokens are printed in logs
• Checked that unrelated jobs are not affected — enforce_latest only edits the "Latest" flag and is gated on release_published

Reference logic validated by the caller workaround documented in #389:

highest=$(gh release list --repo "$GITHUB_REPOSITORY" --exclude-pre-releases --exclude-drafts \
  --json tagName --jq '.[].tagName' | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)
[ -n "$highest" ] && gh release edit "$highest" --repo "$GITHUB_REPOSITORY" --latest

Caller repo / workflow run: motivating case — https://github.com/LerianStudio/plugin-br-pix-indirect-btg/actions/runs/26657889439/job/78572886408

Consumers that benefit

Any repo consuming release.yml that maintains a maintenance/patch line (semver-minor branch such as maintenance/1.6.x): its patch releases will no longer hijack the "Latest" badge from the main line. Repos with a single linear release history are unaffected (no-op). The caller-side enforce-latest workaround can be removed once consumers bump to the version carrying this change.

Related Issues

Closes #389

Summary by CodeRabbit

• Chores
  • Enhanced release workflow automation to improve latest release designation management.

[coderabbitai]

Walkthrough

This PR adds a new enforce_latest job to the release workflow that runs after successful release publishing to ensure the highest stable semver (vX.Y.Z, excluding pre-releases) is marked as GitHub "Latest". The notify job is updated to depend on this new job and report its status in Slack notifications.

Changes

Enforce Latest Release Marking

Layer / File(s)	Summary
Enforce Latest job and status integration .github/workflows/release.yml	New enforce_latest job queries GitHub releases to find the highest stable vX.Y.Z semver, excludes pre-releases and drafts, and marks that release as Latest. The notify job depends on enforce_latest and extends its Slack failure message to include "/ Enforce Latest" when that job fails.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• #389: This PR implements the workaround described in the issue—adding an enforce_latest job that re-asserts the "Latest" badge to the highest stable semver, preventing maintenance-branch releases from hijacking the Latest marker.
• #384: Both changes address correctness of identifying the latest stable vX.Y.Z release vs. pre-releases.

Suggested labels

workflow, release, github-actions

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly identifies the feature: a new job that enforces the highest stable semver as the GitHub Latest release, directly addressing issue #389.
Description check	✅ Passed	Description covers all template sections: clear problem statement, type of change marked, breaking changes stated as none, testing checklist mostly completed, and issue reference provided.
Linked Issues check	✅ Passed	PR implements the enforce_latest job that directly addresses #389's objective: re-asserting the 'Latest' badge to the highest stable semver after release, using the validated workaround pattern.
Out of Scope Changes check	✅ Passed	All changes are scoped to the enforce_latest job addition and its integration into the release workflow; no unrelated modifications present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/enforce-stable-latest

---

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

[lerian-studio]

⚠️ Invalid Source Branch

Pull requests to main can only come from:

• develop
• hotfix/*

Your source branch: feat/enforce-stable-latest

Please change the base branch or create a PR from an allowed branch.

[lerian-studio]

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check	Status	Blocking
Source Branch	✅ success	yes
PR Title	✅ success	yes
PR Description	✅ success	yes
PR Size	✅ success	no
Auto Labels	✅ success	no
PR Metadata	✅ success	no

---

_{🔍 View workflow run}

[lerian-studio]

🔍 Lint Analysis

Check	Files Scanned	Status
YAML Lint	1 file(s)	✅ success
Action Lint	1 file(s)	✅ success
Pinned Actions	1 file(s)	✅ success
Markdown Link Check	no changes	⏭️ skipped
Spelling Check	1 file(s)	✅ success
Shell Check	1 file(s)	✅ success
README Check	1 file(s)	✅ success
Composite Schema	no changes	⏭️ skipped
Deployment Matrix	no changes	⏭️ skipped

---

_{🔍 View full scan logs}

[lerian-studio]

🛡️ CodeQL Analysis Results

Languages analyzed: actions

✅ No security issues found.

---

_{🔍 View full scan logs | 🛡️ Security tab}

[coderabbitai]

Warning

CodeRabbit couldn't request changes on this pull request because it doesn't have sufficient GitHub permissions.

Please grant CodeRabbit Pull requests: Read and write permission and re-run the review.

👉 Steps to fix this

Actionable comments posted: 2

🤖 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 @.github/workflows/release.yml:
- Around line 359-360: Add a one-line explanatory comment immediately above the
permissions: contents: write override that states why this job needs write
access (e.g., it escalates from the top-level contents: read to allow the
release-editing job to create/update releases and push changelog/release
commits) so reviewers and tooling understand the intentional, least-privilege
exception; reference the permissions: contents: write line in your comment.
- Around line 366-367: The current highest= assignment uses `gh release list`
without an explicit --limit so it can miss the true newest stable tag; update
the `gh release list` invocation (used in the `highest` variable) to include a
sufficiently large `--limit` (e.g. --limit 1000 or another number appropriate
for this repo) while keeping the existing `--exclude-pre-releases` and
`--exclude-drafts` filters so the highest stable vX.Y.Z is computed from the
full fetched set.

🪄 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.yml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8c1cae6c-1050-4685-b2ad-8847827a88e8

📥 Commits

Reviewing files that changed from the base of the PR and between 32d6885 and 2fd194a.

📒 Files selected for processing (1)

• .github/workflows/release.yml