fix(release): fail before tagging when release notes exceed the API limit

[bedatty]

Description

Publishing the first stable release of a repository with a long prerelease history fails late and leaves the repository half-released.

With no previous stable tag, @semantic-release/release-notes-generator builds the notes from the whole history. The GitHub Releases API rejects a body over 125 000 characters, and @semantic-release/github only hits that limit in its publish step — after the tag has been created and pushed. The tag then fires the caller's tag-push build and reaches production, while the Release, the changelog, the announcement and the native backmerge are all skipped. With the stable tag never reaching backmerge_target, the prerelease guard fails every later push to that branch until someone backmerges by hand. This is what happened in LerianStudio/plugin-br-payments (2926 commits, tag v1.0.0 left orphaned).

This PR makes release.yml catch it before anything is published:

• Determine next version (dry-run) now runs on every branch, not only on the prerelease lines. pre_sync only ever runs on a prerelease branch, so on a stable branch its two conditions are vacuously true and the step behaves exactly as before where it already ran.
• Guard against stale prerelease keeps its prerelease-only scope — it gained an explicit is_prerelease == 'true' condition, since the dry-run it depends on is no longer prerelease-gated. No behavior change.
• New step Guard against oversized release notes measures the dry-run notes and fails the run before the real Semantic Release step. On failure there is no tag, no deployed build and nothing to clean up, and the error explains how to unblock.
• New input release_notes_max_chars (number, default 125000, 0 disables).

Not in scope: truncating the notes, or generating them from the last prerelease. Both require replacing @semantic-release/release-notes-generator in the consumer's .releaserc — semantic-release concatenates the results of the generateNotes plugins rather than replacing them, so no additional plugin can shorten another plugin's notes. That would mean this workflow rewriting each repository's .releaserc, which deserves its own issue. This PR delivers what the issue calls the minimum: stop before the tag.

Affected workflow: release.yml (reached by go-release.yml, js-release.yml, self-release.yml).

Type of Change

• fix: Bug fix in a workflow (incorrect behavior, broken step, wrong condition)
• feat: New workflow or new input/output/step in an existing workflow

Breaking Changes

None. The new input defaults to the limit the API already enforces, so the guard can only stop a release that would have failed anyway — one step earlier, and without the orphan tag. The extra dry-run on stable branches adds one semantic-release invocation and publishes nothing.

Testing

• YAML syntax validated locally
• actionlint .github/workflows/release.yml clean
• Verified all existing inputs still work with default values
• Checked that unrelated workflows are not affected
• Triggered a real workflow run on a caller repository using @this-branch or the beta tag

Caller repo / workflow run: n/a — reproducing it needs a repository with no stable tag and a 125k+ character history.

Related Issues

Closes #874

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: LerianStudio/github-actions-shared-workflows/.coderabbit.yml
• Review profile: ASSERTIVE
• Plan: Essentials
• Run ID: 1ff97aad-7690-4896-837c-abd34a5e6c49

---

📥 Commits

Reviewing files that changed from the base of the PR and between be20f9d and f9bc03d.

---

📒 Files selected for processing (2)

• .github/workflows/release.yml
• docs/release.md

---

Limit details: You’ve used the included review currently available. Your 67 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

---

---

Walkthrough

The release workflow adds a configurable limit for dry-run release notes. When notes exceed a positive limit, the workflow fails before the real release step. The documentation describes the limit, its default, and how to disable the check.

Changes

Release Notes Size Guard

Layer / File(s)	Summary
Dry-run release checks .github/workflows/release.yml, docs/release.md	The workflow runs semantic-release dry runs on stable branches and adds a configurable release-notes size guard before the real release step. The prerelease staleness guard now applies only to prerelease branches when a release is pending. The documentation explains the 125,000-character default, the 0 opt-out, and the oversized-notes failure scenario.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: fredcamaral

Fixed issue severity:

Merge Risk: ⚪ Minimal · up to f9bc0

The workflow checks pending release notes before the real release step, and its documented limit behavior matches the implementation. No actionable merge risk remains.

Pre-merge checks | 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check		The title clearly identifies the primary change: preventing oversized release notes from creating a tag before the release fails.
Description check		The description is complete and follows the repository template. It explains the problem, affected workflow, behavior changes, input configuration, scope, breaking changes, validation performed, and r…
Linked Issues check		Issue #874 requires a minimum fix that checks generated release notes during the dry run and stops the workflow before tag creation. The reviewed changes add release_notes_max_chars with a default o…
Out of Scope Changes check		The changes are limited to .github/workflows/release.yml and docs/release.md. The workflow input, dry-run guard, prerelease condition, and related documentation directly support issue #874. No unr…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

---

---

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Usage-based review receipt

• Mode: Continue automatically
• Reviewed files: 2
• Charged: $0.50
• View usage details

Note

This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.

---

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

[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	1 file(s)	✅ success
Spelling Check	2 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]

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check	Status	Blocking
Source Branch	✅ success	yes
PR Title	✅ success	yes
PR Description	✅ success	yes
Breaking Change Guard	✅ success	yes
Commit Signatures	✅ success	yes
PR Size	✅ success	no
Auto Labels	✅ success	no
PR Metadata	✅ success	no

---

_{🔍 View workflow run}

[lerian-studio]

🛡️ CodeQL Analysis Results

Languages analyzed: actions

✅ No security issues found.

---

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

[lerian-studio]

@coderabbitai review

[coderabbitai]

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