Versioning & upgrades

Zynth Auth uses semantic versioning — vX.Y.Z — and the meaning of each part is a guarantee we enforce in our own build pipeline, not a convention. It tells you exactly how much care an upgrade needs before you read the changelog.

Status. The versioning + patching machinery this page describes is built and enforced in our own pipeline (the patch guard runs on every release tag); commercial self-host GA is sequenced last (see Deployment models). This is the committed contract your install runs under.

What each part of the version promises

Change	Version	What it means for you
Patch — `1.4.0` → `1.4.1`	Security and bug fixes only	Safe to apply unattended. No database migrations, no new required configuration, no behaviour change beyond the fix. Fully reversible.
Minor — `1.4.0` → `1.5.0`	New features	May include database migrations (backward-compatible) and new optional settings. Apply through a short runbook with a backup.
Major — `1.x` → `2.0.0`	Breaking changes	Removed or changed contracts. Plan it: read the migration notes, expect config or integration changes. Vendor-assisted.

The important line is the first one. A patch is guaranteed to carry no schema migration and no new required setting — which is precisely what makes it safe to roll back automatically if anything goes wrong. That guarantee is checked by a release gate that fails our build if a patch tries to include either, so it is a property of the artifact you receive, not a promise on a page.

Applying a patch (self-service, unattended)

Patches are designed to apply themselves safely:

zynth-upgrade --patch

This resolves the latest patch in your current minor, verifies every image signature, records your current versions, snapshots the database as a precaution, deploys, and runs a smoke test — and if the smoke test fails, it rolls straight back to what you were running. Because a patch never changes the schema, that rollback is clean: your data is untouched and the previous images simply run again.

You can automate this. A patch that reaches you has already passed our full test suite and the patch gate; the advisory that announces a security fix ships with the patch already available.

Your licence is checked before the upgrade runs

If your install carries a licence, zynth-upgrade checks its maintenance term before deploying anything. A current term proceeds; if you are inside the expiry-warning window it proceeds but warns you to renew; if the term has lapsed, the upgrade is refused with a clear message — new releases require a live maintenance term (you keep everything published while your term was active, forever). Renew and re-run. Installs with no licence configured are unaffected. This is a local safeguard; the same rule is enforced when you download a release, so the two never disagree.

Applying a minor or major

Minor and major upgrades can carry database migrations, so they do not self-apply. They run through a gated runbook: take a backup, apply, verify, with a defined restore point. Minor migrations are always backward-compatible within the minor (expand-then-contract), so a minor upgrade is low-drama — but it is a deliberate, backed-up step, not an unattended one. Major upgrades are planned with vendor assistance.

Which versions are supported

Security fixes are backported to the current minor and the one before it. Older minors need an upgrade to keep receiving fixes. This is published so it is a contract, not a case-by-case conversation — plan to stay within one minor of current.

If something goes wrong

Every upgrade path is reversible by design — a patch automatically, a minor/major from the backup the runbook takes first. If you need to open a support case, the support-bundle command produces a sanitized diagnostic archive (versions, configuration with secrets redacted, recent logs, health) so we can help without access to your infrastructure.

Self-hosting overview — the deployment shape and security posture.
Deployment models — managed SaaS vs. self-host.