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
main branch of the Onyx repository is our development branch.
Docker Hub
Docker Hub hosts the actual container images. New images are published every night from themain branch and when a new release is cut.
To identify the latest images programmatically, use our API endpoint:
Versioning Scheme
Onyx follows Semantic Versioning (SemVer). Standard Version Format:- 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):mainis frozen into a newrelease/vX.Ybranch- Only
vX.Y.0-beta.Npre-releases are cut from this branch
- Only stable
vX.Y.Nreleases are cut from the previous week’s release branch - No new release branch is created
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 likev5.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.Docker Pull Images
Docker Pull Images
Specify the version tag in the environment.
Docker Build Images
Docker Build Images
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
Helm
Helm
To specify a version when deploying with Helm, set the
global: version value in your values.yaml file.values.yaml