Immutable releases on GitHub: what they lock and what they do not

An immutable release is a GitHub release whose assets and Git tag cannot be changed after publication. The tag stays locked to one commit and the files cannot be altered or removed. That blocks one specific attack, swapping contents under an existing version, but it does not tell users the contents were good in the first place.

What gets locked

According to GitHub's documentation:

• The tag is locked to a specific commit and cannot be changed or deleted while the release exists.
• The assets, such as binaries and archives, are protected from modification or deletion.
• An attestation is generated automatically. It records the release tag, commit SHA and assets so consumers can check that what they downloaded matches the published release.

Why maintainers should care

A common supply chain move is to take an existing version and quietly replace its files, or to move a tag to a different commit. Anyone who pinned that version then gets different code. Immutability closes that door for releases you publish.

It also helps your own users. If someone asks "is this the same file you released in March?", the attestation gives an answer that does not depend on trusting your account.

What stays editable

GitHub says you can still change:

• The release title and notes
• Whether it is a pre-release
• Whether it is marked as the latest release

That is useful, because you can fix a typo in the notes without breaking the lock. It is also a reminder that release notes are not part of the guarantee.

The workflow that fits

GitHub recommends creating the release as a draft, attaching every asset, then publishing. Assets must be in place before the lock engages, so a late upload is not possible. Build this into your release workflow:

1. Build artifacts in CI.
2. Create a draft release.
3. Upload every artifact.
4. Publish.

Pair this with checksums in the release notes and a documented verification step, so users know how to check a download. The broader checklist is in open source release security.

Trade-offs to plan for

• Deleted tag names cannot be reused. If you delete an immutable release you can delete the tag, but you cannot reuse that tag name. Pick version numbers with that in mind.
• A bad release stays bad. You cannot patch the assets. You publish a new version and, where needed, deprecate the old one. See yank, unpublish or deprecate.
• It covers GitHub releases. Packages on registries and container images have their own mechanisms.

What it does not prove

A lock on a bad file is still a lock. Immutability says the file did not change after you published it. It does not say the build was clean or that the source was reviewed. Provenance, review and a hardened build pipeline do that work.

Safeguard can scan the dependencies your release pulls in and flag known issues before you publish. A free scan is at gold.safeguard.sh/scan.

Quick check

Sources

• Immutable releases (GitHub Docs)

Last reviewed: 19 October 2026.