This page explains Onyx’s release process, versioning scheme, and how updates are delivered to different deployment channels.

​
Release Channels

Onyx maintains multiple release channels to provide stable and development versions for different use cases.

​
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: 
https://cloud.onyx.app/api/versions
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) with a clear, predictable format. Standard Version Format: 
major.minor.hotfix
Pre-release Version Format: 
major.minor.hotfix-beta.betahotfix
Examples:
  • Stable release: 1.2.3
  • Pre-release: 1.3.0-beta.1
  • Beta hotfix: 1.3.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 follows a predictable weekly release cycle. Every Monday:
  1. The last pre-release version is promoted to stable
  2. main is frozen as the new pre-release

​
Hotfix Process

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

​
Deployment Best Practices

Monitor the /api/versions endpoint to automate deployment workflows. Stay tuned to our Github and join our Slack to stay informed about new releases and breaking changes. Choose the right version for your deployment environment:
  • Production environments - Use stable releases only
  • Staging/testing environments - Use pre-release versions to validate upcoming changes
  • Development environments - Contributors should fork from main