asemantic-release

Releases need identity, order, and immutability — not semantics.

asemantic-release (asr) is a zero-dependency CLI that automates application releases: promotion to production retags the container image that already passed testing — registry-side, by digest — mints an ordered CalVer tag, records it as an annotated git tag, and pins it in a deployment repo. Rolling back is one command. No commit conventions, no changelog bots, no version arithmetic.

Why

Semantic Versioning encodes API compatibility so downstream consumers can judge whether an upgrade is safe, and semantic-release automates that judgment from commit messages. For published libraries this is the right tool.

A deployed application has no downstream consumers reading its version number. Its version has exactly three jobs:

• identify an exact, immutable build artifact,
• order releases, so "the previous one" is well defined,
• stay readable for the human operating a rollback.

None of this is a new idea — it is what continuous-delivery practice already requires. "Build once, deploy many" means the artifact validated in pre-production is byte-for-byte what runs in production; rebuilding per environment is a well-documented anti-pattern. MAJOR.MINOR.PATCH adds nothing to these three jobs, yet using it for an app still costs a team-wide commit-message contract, enforcement tooling (commitlint, Commitizen), CI plumbing, and a release bot fighting protected branches.

asr implements the three jobs directly and drops the rest.

How it works

• Below production, the commit SHA is the version. Dev and staging deploy raw SHA-tagged images with no release ceremony.
• A release happens only at promotion to production. asr promote resolves the digest of the tested image and retags it in the registry — via crane, skopeo, or docker buildx imagetools, no pull, no rebuild — so the shipped bytes are provably the tested bytes.
• Tags are CalVer: r2026.07.11, then r2026.07.11-2 for the second release that day. Unique, chronologically ordered, and the tag itself says how old the release is.
• Every release is an annotated git tag carrying the image reference and digest — the audit trail lives in the repo you already have.
• Rollback moves the pin in the deployment repo back to a release whose image already exists in the registry — no rebuild, no revert commit.
• Release notes come from merged pull request titles (both merge commits and squash merges), which get reviewed — not from commit messages, which don't.

Where it fits

Different setups need different tools:

• Publishing a versioned library? SemVer does real work there — tools like semantic-release or Changesets fit better.
• Running Kubernetes with Argo CD or Flux? That ecosystem has its own promotion tooling (Kargo, Argo CD Image Updater, Flux image automation).
• Everything else — apps on VMs, docker-compose, plain Helm, a single cluster, a small team — is what asr is for: the same promotion pattern as one small CLI and a JSON config, with no cluster components to run.

Install

npm install -g @fissel72/asemantic-release   # or: npx @fissel72/asemantic-release

The package lives under a scope because npm's typosquat protection reserves unscoped names this close to semantic-release — see the non-affiliation note below. The binary is plain asr either way.

Requires Node.js >= 20 and git. promote uses the first available of crane, skopeo, or docker (configurable via backend).

Usage

asr next                    # print the tag the next promotion will mint
asr tags                    # list release tags, oldest first (* = currently pinned)
asr promote --image <ref>   # retag tested image as next release (by digest), git tag, pin deploy repo
asr rollback                # move the deployment pin back one release
asr rollback --to <tag>     # pin an explicit release
asr notes                   # release notes from merged PR titles since the last release
asr notes <tag>             # release notes for an existing release

Every command accepts --dry-run (print every action, execute nothing) and --config <dir> (directory containing .asrrc.json, default cwd).

A promotion, concretely

$ asr promote --image registry.example.com/shop:abc1234
> crane copy registry.example.com/shop@sha256:4f2a... registry.example.com/shop:r2026.07.11
> git tag -a r2026.07.11 -m image registry.example.com/shop:r2026.07.11 ...
> git push origin r2026.07.11
pin D:\deploy\values.yaml -> r2026.07.11
> git -C D:\deploy commit -m release r2026.07.11 -- values.yaml
> git -C D:\deploy push
r2026.07.11

Second release the same day mints r2026.07.11-2, third -3, and so on. Bare tag = release 1.

Configuration — .asrrc.json

{
  "image": "registry.example.com/shop",
  "deployRepo": "../shop-deploy",
  "deployFile": "values.yaml",
  "deployPattern": "tag: \"{tag}\"",
  "branch": "main",
  "backend": "auto",
  "prefix": "r",
  "dateFormat": "YYYY.MM.DD",
  "remote": "origin"
}

key	default	meaning
image	—	registry image name promotions retag to (required for promote)
deployRepo	—	path to the deployment repo, relative to the config dir
deployFile	—	file inside deployRepo holding the pinned tag
deployPattern	—	literal line with a {tag} placeholder; works on any text file — Helm values, Compose, .env
branch	—	if set, promote refuses to run from any other branch
backend	auto	crane, skopeo, imagetools, or docker; auto picks the first available in that order
prefix	r	tag prefix
dateFormat	YYYY.MM.DD	YYYY/MM/DD tokens; keep it big-endian so tags sort chronologically
remote	origin	git remote release tags are pushed to

If deployRepo/deployFile/deployPattern are unset, promote still retags, pushes, and git-tags — it just skips the pin step.

The crane, skopeo, and imagetools backends work registry-side against the image you already pushed and tested. The docker backend (docker tag + docker push) is a local-daemon fallback; it works, but cannot guarantee digest-identical promotion.

Known limitations

• notes covers merge commits and GitHub-style squash subjects (Title (#123)). GitLab-style squash merges and edited squash subjects are not detected; a GitHub API / gh pr list fallback is a candidate for a future release.
• promote assumes the image is already pushed under its test tag (registry backends) or present in the local daemon (docker backend).
• One pin per config. Multi-stage promotion pipelines with verification gates are deliberately out of scope; various other tools cover that space.

Development

Two custom agentic workflows support development: a release audit that checks a branch for drift between code, README, and package metadata, and a release notes generator that verifies each line against the actual diff before publishing. Both run on demand on a small purpose-built agent harness — see agents/README.md. They are dev-side only; the shipped CLI has no AI in it.

Non-affiliation

This project is not affiliated with, endorsed by, or related to semantic-release. The name is a deliberate antonym — it stands for the opposite philosophy, in the same spirit as unfetch.

License

MIT