---
title: "Make release tags and files immutable · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/build-test-and-deploy/immutable-releases
updated: 2026-10-21
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 [Build, test and deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy.md).

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

- ID: ENG-42
- Level: Recommended
- Chapter: [Build, test and deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy)
- Rule: Once a release is published, its tag never moves and its files never change. A fix ships as a new version.
- 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) says. Consumers verify the files as [Build releases only in CI and verify them before deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/build-in-ci-and-verify) 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) shows.
- 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.

## 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

- [Stamp every build with its version](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/version-every-release) in Engineering
- [Build releases only in CI and verify them before deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/build-in-ci-and-verify) in Engineering
- [Use Trivy for the bill of materials and cosign to sign releases](https://agentwranglers.se/playbook/stack/delivery-and-infrastructure/sbom-and-signing) in Software choices

**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/build-test-and-deploy/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/build-test-and-deploy/build-in-ci-and-verify)
- Next: [Roll out settings and data files like code](https://agentwranglers.se/playbook/engineering/build-test-and-deploy/staged-config-rollouts)
- [Build, test and deploy](https://agentwranglers.se/playbook/engineering/build-test-and-deploy)