Skip to content

Github immutable tags are insane

EN

How Github's unacceptable feature design can ruin your versioning

rantgithubissuedeveloper-experience

There is a feature on GitHub designed to protect you. Instead, it punishes you, permanently, and without appeal. It is called Immutable Releases, and if you are reading this because you are currently locked out of your own repository tag, welcome to the club. Pull up a chair. You are not getting that tag back.

What Happened

My public project repository 4ster-light/sentinel, hit this wall just today. A release was created for tag v0.2.1. It was a mistake. The release was deleted. The tag was deleted locally and on the remote. Clean slate, right?

Wrong

Attempting to recreate the tag:

1git tag v0.2.1 && git push origin v0.2.1 --force

GitHub responded with this:

1remote: error: GH013: Repository rule violations found for refs/tags/v0.2.1.2remote: Review all repository rules at https://github.com/4ster-light/sentinel/rules?ref=refs%2Ftags%2Fv0.2.13remote:4remote: - Cannot create ref due to creations being restricted.5remote:6To github.com:4ster-light/sentinel.git7 ! [remote rejected] v0.2.1 -> v0.2.1 (push declined due to repository rule violations)

The tag does not exist on remote or local. The release does not exist. But GitHub simply says no.

The Debugging Nightmare

https://github.com/4ster-light/sentinel/rules?ref=refs%2Ftags%2Fv0.2.1

The error message points to a "rules" page. Naturally, the first instinct is to go check these rules. The rules page shows literally nothing. No rulesets. No branch protection rules. No tag protection rules. Just an empty page mocking you with a "New ruleset" button.

Fine. Maybe it is somewhere else. Check Settings → Branches. Nothing relevant. Check Settings → Tags. Nothing. Check Settings → Rules → Rulesets. Nothing. At this point, in desperation, I go for the nuclear option: clicking "Disable branch protection rules" which explicitly warns about disabling all enforcement. Done. Push again.

Same error. Same wall. Feels like it is laughing at you.

The error message is actively lying by pointing to rules that do not exist and a rules page that shows nothing. It is a dead end dressed up as a diagnostic tool.

The Actual Cause: A Feature GitHub Buried in the Fine Print

GitHub shipped Immutable Releases as a general availability feature in October 2025. The pitch is reasonable: once a release is published and marked immutable, its tag and assets cannot be silently swapped out. This is a real supply chain security concern and it is great that they cared to bring a counter-measure.

But buried deep in the documentation is this sentence:

If you delete the immutable release, you can delete the tag, but you cannot reuse the same tag name.

And this one:

Disabling immutability doesn't affect releases created while it was enabled — they remain immutable.

So if v0.2.1 was ever associated with an immutable release, even for five minutes, even accidentally, even if the release is now completely gone. The tag name v0.2.1 is permanently blacklisted. No API. No admin override. No support ticket. No exception. Forever.

Why This Design Is Inexcusable

You could argue all this should be expected behavior from a solid, truly immutable safety feature, but, there are a few reasons I still find this at best a messy implementation:

There Is No Warning

When a release is marked as immutable, GitHub does not say: "Warning: deleting this release will permanently blacklist this tag name across your entire repository, forever, with no recovery path." It just... does it. Silently. The consequence is permanent and irreversible, and the user is given zero indication of this at the moment it matters.

The Error Message Is Useless

GH013: Repository rule violations found for refs/tags/v0.2.1 is probably one of the most misleading error messages I can think of in modern software. It points to rules. There are no rules. The actual cause, an immutable release record, is never mentioned. A developer debugging this blind would spend hours checking protection rules, rulesets, organization policies, and API permissions before stumbling on the real answer, if they ever do, which is basically what happened to me after several hours of digging in the internet looking for a straight answer.

There Is No Admin Override

This is a personal repository. 4ster-light, ME, is the sole owner, admin, and (at least for now) contributor. There is no organization policy being enforced here, no compliance requirement, no external authority. The repository owner should have the absolute right to modify as pleased, given proper authentication of course. Instead, GitHub has decided that a deleted release ghost takes precedence over the living, breathing, human owner of the repository. That is an obscene inversion of user control.

"Security Feature" Does Not Mean "Punish Mistakes"

The legitimate use case for immutable releases is preventing tampering with intentionally published artifacts. It is not meant to trap developers who accidentally clicked the wrong button. A sane implementation would include:

  • A grace period (e.g., 24 hours) before immutability locks in
  • An explicit confirmation warning: "This action is permanent and cannot be undone"
  • An admin/owner escape hatch for personal repositories
  • An honest error message that names the actual cause

None of these exist. GitHub shipped the lock and forgot to ship the key.

The Community Has Noticed

The semantic-release project hit this exact wall in 2026, their automated release tooling kept trying to push a tag that had been used by an immutable release, creating an unrecoverable loop. This is not an edge case. Any CI/CD pipeline that creates and then cleans up releases will eventually walk into this trap.

https://github.com/semantic-release/semantic-release/issues/4147

Community discussion on GitHub's own forums confirms that even the people who like immutable releases find the lack of a recovery path baffling.

https://news.ycombinator.com/item?id=45772064

Conclusion

Anyways, I know this isn't as one sided of an opinion as I have presented it in this blog. This is mostly a rant purely out of frustration due to the issues I have experienced in my own project and for the reasons I have already stated how exasperating I find the whole context of the situation. I am not the only one that thinks this way but I assume one could make the argument that enabling this feature, which is opt-in, is on me, anyways, future releases will not be immutable on sentinel and, testimony lies here of how they can turn out annoying and what are their shortcomings in terms of DX.