---
title: "Release Caracal"
url: "https://docs.caracal.run/contributing/release/"
markdown_url: "https://docs.caracal.run/markdown/contributing/release.md"
description: "CalVer releases, package publishing, protected workflows, and rollback rules."
page_type: "reference"
concepts: []
requires: []
---

# Release Caracal

Canonical URL: https://docs.caracal.run/contributing/release/
Markdown URL: https://docs.caracal.run/markdown/contributing/release.md
Description: CalVer releases, package publishing, protected workflows, and rollback rules.
Page type: reference
Concepts: none
Requires: none

---

Caracal release artifacts use CalVer product versions and package versions defined in `release.config.json`.

## Release Surfaces

| Surface | Source |
| --- | --- |
| Product version | `release.config.json` product version, currently `2026.06.25-rc.1`. |
| Runtime binary | `apps/runtime/dist/caracal-*`. |
| Containers | API, STS, Gateway, Audit, Coordinator, Control, Postgres, Redis, Runtime. |
| Helm | `infra/helm/caracal`. |
| npm packages | Public `@caracalai/*` packages from `release.config.json`. |
| PyPI packages | Public `caracalai-*` packages from `release.config.json`. |

## Build Targets

Runtime release builds compile Linux x64/arm64, macOS x64/arm64, and Windows x64 binaries through Bun compile scripts.

Go-based service container builds preserve debug information by default and honor native build arguments passed to Docker: `CGO_ENABLED`, `CC`, `CFLAGS`, `CXX`, `CXXFLAGS`, `LDFLAGS`, `GOFLAGS`, `GO_BUILDFLAGS`, and `GO_LDFLAGS`. The Dockerfiles add `-mod=readonly` and `-trimpath`; pass linker options through `GO_LDFLAGS` for diagnostic or release-specific builds.

## Release Flow

| Stage | Command pattern |
| --- | --- |
| RC prepare | `scripts/release.sh rc prepare --base-version <YYYY.MM.DD> --suffix rc.1` |
| RC dry run | `scripts/release.sh rc dry-run --base-version <YYYY.MM.DD> --suffix rc.1 --local` |
| Stable dry run | `scripts/release.sh stable --dry-run` |
| Stable publish | `scripts/release.sh stable` |

Protected GitHub workflows publish npm and PyPI packages. Local stable publishing requires explicit approval and environment override.

## Changesets

Only public `@caracalai/*` packages under `packages/` are released through Changesets. Internal-only packages must stay in the Changesets ignore list.

## Rollback Rule

Do not delete published tags. Roll forward with a new CalVer tag. Pinned `v<calver>` tags are immutable; floating monthly tags move with the new cut.

## Related Pages

- [Release Map](/reference/release-package-runtime-map/)
- [Upgrade Caracal](/operations/upgrade/)