fix: first stable release fails on oversized release notes and leaves an orphan tag #874

Affected Workflow

Release & Versioning (release): release.yml, called by go-release.yml

Workflow Version / Ref

@tier-2, with semantic-release 23.0.8 through cycjimmy/semantic-release-action@b12c8f60 (release.yml:439)

Bug Description

Publishing the first stable release of a repository with a long prerelease history fails, and the failure leaves the repository in a half-released state.

With no previous stable tag, @semantic-release/release-notes-generator builds the notes from the repository's whole history. In LerianStudio/plugin-br-payments that was 2926 commits. @semantic-release/github → publish then sends that body to the Releases API, which rejects anything over 125,000 characters.

The failure happens late:

1. The tag v1.0.0 has already been created and pushed. The tag push fires the caller's tags: ['**'] trigger, so the build, the S3 upload and update_gitops all run: the version reaches production.
2. No GitHub Release is created. The changelog, the release announcement and the native backmerge main → develop are all skipped.
3. Because the stable tag is not reachable from develop, semantic-release on develop keeps computing 1.0.0-beta.N. The prerelease-vs-stable guard then fails every push to develop ("v1.0.0 is already released as stable. develop is out of sync with main") until someone backmerges by hand.

Any repository whose first stable release comes after a long beta/rc cycle will hit this. That is the normal path for the portfolio's plugins.

Steps to Reproduce

1. A repository with prereleases only (v1.0.0-beta.1..177, v1.0.0-rc.1..13) and no stable tag.
2. Promote release-candidate to main and let go-release run on main.
3. The run fails in publish, and tag v1.0.0 is left behind with no Release attached.

Expected Behavior

The first stable release publishes. Some possible fixes:

• When there is no previous stable, generate the notes from the last prerelease on the promoted channel (for example, the last -rc.N).
• Truncate the release body under the 125k limit and link to the full compare.
• At minimum, check the notes size in the dry-run step (release.yml:417, which already computes the notes) and fail before the tag is created, so the pipeline never leaves a tag without a Release.

Relevant Logs / Error Output

[semantic-release] › ℹ  Analysis of 2926 commits complete: major release
[semantic-release] › ℹ  There is no previous release, the next release version is 1.0.0
[semantic-release] › ✔  Created tag v1.0.0
[semantic-release] › ✘  Failed step "publish" of plugin "@semantic-release/github"
HttpError: Validation Failed: {"resource":"Release","code":"custom","field":"body","message":"body is too long (maximum is 125000 characters)"}

• Release run on main: https://github.com/LerianStudio/plugin-br-payments/actions/runs/37949176218
• Tag-push run that reached production anyway: https://github.com/LerianStudio/plugin-br-payments/actions/runs/37949316980
• develop run blocked by the guard afterwards: https://github.com/LerianStudio/plugin-br-payments/actions/runs/37951083062

Manual recovery applied: the GitHub Release v1.0.0 was created by hand with notes from v1.0.0-rc.13, and the backmerge was opened as LerianStudio/plugin-br-payments#509.

Caller Workflow Configuration

jobs:
  pipeline:
    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@tier-2
    with:
      enable_changelog: ${{ github.ref == 'refs/heads/main' }}
      enable_gitops_artifacts: true
      gitops_yaml_key_mappings: '{"plugin-br-payments.tag": ".app.image.tag"}'
      extra_builds: '[{"filter_paths":"cmd/fakebtg","path_level":2,"app_name_overrides":"cmd/fakebtg:fakebtg"}]'
      s3_uploads: '[...]'
    secrets: inherit

.releaserc.yml uses only the core plugins (commit-analyzer, release-notes-generator, github) and declares the branches main, release-candidate (rc) and develop (beta).

Runner OS

Self-hosted (blacksmith-4vcpu-ubuntu-2404)