---
title: "Make release tags and files immutable · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/immutable-releases
id: ENG-42
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1202
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Make release tags and files immutable

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ENG-42
- Level: Recommended
- Chapter: [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md)
- Rule: Once a release is published, its tag never moves and its files never change. A fix ships as a new version.
- Check: Point an existing release tag at another commit and force-push it. The code host refuses the push. Try to delete or replace a file of a published release. The code host refuses that too.
- How: A moved tag or a swapped release file ships code under a version that people already trust and tested. Turn on immutable releases in GitHub, or protect release tags in GitLab, so nobody can move or delete them. Create the release as a draft, attach every file, then publish it, because the files lock when it is published. Name versions as [Stamp every build with its version](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release.md) says. Consumers verify the files as [Build releases only in CI and verify them before deploy](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/build-in-ci-and-verify.md) describes. Sign each release file as [use Trivy for the bill of materials and cosign to sign releases](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/sbom-and-signing.md) shows.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```sh
# Publish: attach every file to a draft, then publish once
gh release create v2.4.1 --draft --verify-tag shop.tar.gz shop.sbom.json
gh release edit v2.4.1 --draft=false

# Check: moving a published tag must fail
git tag -f v2.4.1 HEAD
if git push --force origin v2.4.1; then echo "FAIL: release tag moved"; exit 1; fi
```

## Sources

- [GitHub: Immutable releases](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases)

## Related rules

- ENG-7 [Stamp every build with its version](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release.md) in Engineering
- ENG-11 [Build releases only in CI and verify them before deploy](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/build-in-ci-and-verify.md) in Engineering
- STK-95 [Use cosign to sign release images and their bill of materials](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/sbom-and-signing.md) in Software choices
- ENG-59 [Sign release tags and require verified commits on main](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/signed-commits-and-tags.md) in Engineering
- STK-107 [Use Harbor or your code host's registry for container images](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/container-registry.md) in Software choices
- DSK-4 [Check every signature in CI before you publish](https://agentwranglers.se/playbook/desktop-apps/signing-and-notarisation/verify-before-publish.md) in Desktop apps and extensions
- OSS-19 [Tell users how to verify a release](https://agentwranglers.se/playbook/open-source/releases/verification-instructions.md) in Open source maintenance
- OSS-41 [Deleting a published version that others depend on](https://agentwranglers.se/playbook/open-source/funding-and-the-end-of-a-project/no-unpublish.md) in Open source maintenance
- DEV-18 [Publish a checksum and a signature with every download](https://agentwranglers.se/playbook/developer-tools/distribution/checksums-and-signatures.md) in Developer tools, SDKs and CLIs

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/immutable-releases">Agent Wranglers engineering playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Build releases only in CI and verify them before deploy](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/build-in-ci-and-verify.md)
- Next: [Build releases without a shared cache](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain/no-cache-in-release-builds.md)
- [CI and supply chain](https://agentwranglers.se/playbook/engineering/ci-and-supply-chain.md)