Skip to main content
This page is the compatibility contract: what Omniflow is tested against, how a release is identified and verified, how far behind an installation may fall before upgrading, and how a deprecated capability is retired instead of silently removed.

​
Compatibility matrix

Go and Bun are contributor requirements, not operator requirements. An installation runs the images published to ghcr.io/kewldan/omniflow/* and never needs a Go or Bun toolchain on the host.
This table describes what the current main line is tested and built against. A future 1.x release that changes a supported version updates this row, and a version bump that removes support for something in this table is called out in CHANGELOG.md rather than silently dropped — see Deprecation policy.

​
Versioning and release artifacts

Releases follow Semantic Versioning and are cut by Release Please from Conventional Commits, which also generates CHANGELOG.md — nothing is hand-written after the fact. Each tagged release publishes four multi-arch (linux/amd64, linux/arm64) container images to GitHub Container Registry:
Every image is also tagged X.Y so a deployment can track a minor line without floating on latest.

​
SBOM, provenance, and signatures

Every image build attaches an SBOM and SLSA-style build provenance (docker/build-push-action’s sbom: true and provenance: mode=max), and is then signed keyless with cosign using the release workflow’s own GitHub Actions OIDC identity — there is no signing key to manage, rotate, or leak. The signature is recorded in the public Rekor transparency log. Verify an image before deploying it:
Inspect the attached SBOM and provenance with docker buildx imagetools inspect --format '{{ json .SBOM }}' ghcr.io/kewldan/omniflow/api:vX.Y.Z (and .Provenance for the build provenance).

​
Upgrade testing

CI’s migrations job proves every supported upgrade path before a change merges: it applies the schema from an empty database through every prefix of the migration history to head, and confirms re-applying head a second time is a no-op. That is what “automated upgrade tests” means in practice — a migration that only compiles is unverified, so this runs against a real PostgreSQL on every change, not only at release time. The step-by-step upgrade, rollback, and PostgreSQL major-version upgrade procedures live in Backup, restore, and disaster recovery rather than being duplicated here.

​
Migration policy and supported upgrade window

  • Migrations are forward-only. Omniflow does not ship down-migrations; a schema rollback is a restore from the backup taken immediately before the upgrade, as described in Rolling back.
  • A migration is never edited after it has shipped in a release. A schema change always ships as a new migration, and its checksum in database/migrations/atlas.sum is generated by atlas migrate hash, never hand-edited.
  • Upgrades apply sequentially through released versions — the supported upgrade window is exactly what CI’s migrations job tests as a baseline: every prefix of the migration history to head. There is no supported path that skips applying an intermediate release’s migrations; the migrate service applies whatever has not yet run, in order, every time the stack starts.
  • Applying migrations twice is always safe: Atlas records what has already run and a re-apply is a no-op.

​
Deprecation policy

A deprecation is announced before it is removed, and removal is always a CHANGELOG.md entry — never a silent behavior change.
  • API. A deprecated OpenAPI operation or field is marked deprecated: true in api/openapi.yaml and keeps working for at least one further minor release before it can be removed.
  • Environment variables. A deprecated variable keeps working, its replacement is documented alongside it for at least one minor release, and its eventual removal is called out in CHANGELOG.md rather than causing a silent startup-behavior change.
  • Database behavior. A behavior change ships additively first — a new column or table alongside the old one — rather than rewriting existing behavior in the same release that introduces its replacement. The transition itself, not just the endpoint, is a reviewed migration.
  • Integrations. A Remnawave or payment-provider adapter supports the versions actually exercised by its contract tests, published in the compatibility matrix above. Dropping support for a version is a CHANGELOG.md entry, not a silent contract-test change.

Deployment

Compose topology, volumes, and the images this matrix describes.

Backup, restore, and disaster recovery

The step-by-step upgrade, rollback, and PostgreSQL major-version upgrade procedures.