Skip to main content

Release Channels

GitHub

Our GitHub Releases publish images to Docker Hub. Onyx has two types of releases:
  • Latest stable version - Production-ready releases
  • Pre-release version - Beta releases for testing
The main branch of the Onyx repository is our development branch.
Although we try to keep main stable through CI/CD tests and code reviews, we do not recommend using main in production environments.

Docker Hub

Docker Hub hosts the actual container images. New images are published every night from the main branch and when a new release is cut. To identify the latest images programmatically, use our API endpoint:
This endpoint returns the current latest stable and beta versions available on Docker Hub.
If you don’t specify a version when deploying Onyx, you will get the latest nightly builds.

Versioning Scheme

Onyx follows Semantic Versioning (SemVer). Standard Version Format:
Pre-release Version Format:
Examples:
  • Stable release: 1.2.3
  • Pre-release: 5.1.0-beta.1
  • Beta hotfix: 5.1.0-beta.2
  • Major version - Incremented on breaking changes
  • Minor version - Incremented on new features, bugfixes, and backwards-compatible changes
  • Hotfix version - Incremented only when backporting bugfixes to releases

Docker Files and Helm Charts

Changes to Docker files and Helm charts increment the version numbers in their respective files.

Release Schedule

Onyx ships a new minor release every two weeks. Each release has a two-week cycle: Week 1 (pre-release):
  • main is frozen into a new release/vX.Y branch
  • Only vX.Y.0-beta.N pre-releases are cut from this branch
Week 2 (stable):
  • Only stable vX.Y.N releases are cut from the previous week’s release branch
  • No new release branch is created
The next cycle starts the following week with release/vX.(Y+1).

Hotfix Process

  • Critical bug fixes are backported to stable releases as necessary
  • Hotfixes bypass the normal two-week cycle for urgent production issues
  • Both stable and pre-release branches receive hotfixes when applicable

Update Best Practices

To maintain a stable deployment, we recommend staying on the latest stable release. These are tagged with a version number like v5.0.0.
1

Check Versions API for Stable Version Tag

Compare your current version with the version tag of the latest stable release. The versions endpoint is public and does not require authentication.
Look for the stable: onyx key in the response.
Example Response
2

Launch Onyx with the Version Tag

Don’t forget the v prefix! I.e. v5.0.0 is correct, 5.0.0 is incorrect.
Specify the version tag in the environment.
Pull the release branch from GitHub or just the tagged version and build the images.The release branch is where the latest stable version is published. Release branches are named release/v<MAJOR>.<MINOR>.In the Onyx repo:
From Release Branch
From Tagged Version
To specify a version when deploying with Helm, set the global: version value in your values.yaml file.
values.yaml