Immutable releases: "you can only edit the title and release notes" is inaccurate

[koistya]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

Managing releases in a repository, the note under "Editing a release".

What part(s) of the article would you like to see updated?

The note reads:

If you have enabled immutable releases for your repository, you can only edit the title and release notes after a release is published.

prerelease and make_latest are editable too, so the allowlist is wrong. It also contradicts Immutable releases, which lists the enforced protections as exactly two: Git tags cannot be moved, and release assets cannot be modified or deleted.

Measured on a repository with immutable releases enabled, against a published prerelease carrying one asset:

Action	Result
PATCH /repos/{owner}/{repo}/releases/{release_id} with prerelease=false and make_latest=legacy	accepted; the release stays "immutable": true, is no longer a prerelease, and make_latest is honored
edit the title and notes	accepted
upload an asset	422 Cannot upload assets to an immutable release
delete an asset	Cannot delete asset from an immutable release
move the tag	[remote rejected] push declined due to repository rule violations

Read literally, the note says a published prerelease can never be promoted to stable under immutable releases. That would rule out publishing a prerelease, verifying the published assets by downloading them the way a user does, and only then clearing the prerelease flag — a draft release is not public, so the download path a consumer uses cannot be exercised before publication. The note discourages a release process that immutability in fact supports.

Suggested wording, a denylist matching the concepts page:

If you have enabled immutable releases for your repository, you cannot add, replace, or delete assets, or move the tag, after a release is published. Other details can still be edited, including the title, the release notes, and whether the release is a prerelease or the latest release.

Additional information

To reproduce: enable immutability on a throwaway repository with gh api repos/OWNER/REPO/immutable-releases -X PUT, publish a prerelease with an asset, then attempt each action above.

Scope of the measurement: name, body, prerelease and make_latest were tested. I did not test tag_name, target_commitish, draft or discussion_category_name on an immutable release.

[subatoi]

Thanks for raising an issue, @koistya, we'll investigate and come back as soon as possible

[guntrip]

Hi there @koistya, thanks for opening this! ✨

I agree it would be helpful for this to be documented, especially in the release cycle example you gave. Would you like to open a PR to make changes to both pages?

[koistya]

@guntrip sure → #45730