# Onyx Release History: Semantic Versioning and Automated Deployment

> Explore the Onyx release history using semantic versioning. Learn how Git tags trigger automated deployments for container images Helm charts and GitHub releases.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: release-history
- Published: 2026-03-28

---

**Onyx (formerly Danswer) tracks its release history through Git tags prefixed with `v` (e.g., `v7.0.15`), which trigger the ODS (Onyx Development System) to automatically build container images, update Helm charts, and publish GitHub releases.**

The `onyx-dot-app/onyx` repository does not maintain a static changelog file. Instead, the **Onyx release history** lives entirely within the Git tag namespace and is parsed dynamically from MDX fragments stored in the codebase.

## How Onyx Versioning Works

### Semantic Versioning and Tag Format

Onyx follows **semantic versioning** using tags that must start with the letter `v`. When a developer pushes a tag formatted as `v<MAJOR>.<MINOR>.<PATCH>`, the repository recognizes it as a release candidate.

In [`tools/ods/internal/_version.py`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/_version.py), the system reads the `GITHUB_REF_NAME` environment variable to determine the current version, defaulting to `v0.0.0-dev` when no tag is present:

```python

# tools/ods/internal/_version.py

version = os.getenv("GITHUB_REF_NAME", "v0.0.0-dev")

```

This design ensures that development builds are explicitly marked as pre-release versions while production builds carry the official semantic version tag.

### The ODS Release Pipeline

The **Onyx Development System (ODS)** is a CLI tool that automates the entire release workflow. When a `v`-prefixed tag is pushed to GitHub, ODS validates the version string, builds Docker images, updates deployment manifests, and creates a GitHub release entry.

According to [`tools/ods/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md), the pipeline deploys automatically when tags are pushed, orchestrating Helm-chart and Docker-compose deployments without manual intervention.

## Where Release History Is Stored

### Git Tags as the Source of Truth

Unlike projects that maintain a [`CHANGELOG.md`](https://github.com/onyx-dot-app/onyx/blob/main/CHANGELOG.md) file, Onxy encodes its release history directly in Git. You can view the complete timeline using standard Git commands:

```bash
git tag -l "v*" --sort=-version:refname

```

Notable versions observable in the source include:
- **`v2.12`** – Referenced in test fixtures within [`tools/ods/internal/git/git_test.go`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/git/git_test.go) as a valid release tag example
- **`v7.0.15`** – Listed in [`deployment/helm/charts/onyx/values.yaml`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/helm/charts/onyx/values.yaml) as the current chart version at the time of the snapshot
- **`v0.0.0-dev`** – The fallback default used for local development builds

### MDX-Based Release Notes

Release notes are not static documents but MDX fragments parsed at runtime. The backend utilities in [`backend/onyx/server/features/release_notes/utils.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/release_notes/utils.py) convert these files into structured `ReleaseNoteEntry` objects:

```python
from onyx.server.features.release_notes.utils import parse_mdx_to_release_note_entries
from pathlib import Path

mdx_path = Path("docs/release_notes/v8.1.0.mdx")
entries = parse_mdx_to_release_note_entries(mdx_path.read_text())
for entry in entries:
    print(f"- {entry.title}: {entry.body}")

```

The `ReleaseNoteEntry` model defined in [`backend/onyx/server/features/release_notes/models.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/release_notes/models.py) provides the schema used by the API to serve release information to the frontend.

## Key Source Files Driving the Release Process

Several critical files govern how versions propagate through the Onyx ecosystem:

| File | Role |
|------|------|
| [`tools/ods/internal/_version.py`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/_version.py) | Reads `GITHUB_REF_NAME` and defaults to `v0.0.0-dev` for untagged builds |
| [`tools/ods/cmd/cherry-pick.go`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/cmd/cherry-pick.go) | Handles back-porting commits and normalizes version strings with the `v` prefix |
| [`tools/ods/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md) | Documents the ODS workflow and automatic deployment triggers |
| [`backend/onyx/server/features/release_notes/utils.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/release_notes/utils.py) | Parses MDX release notes into database entries |
| [`deployment/helm/charts/onyx/values.yaml`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/helm/charts/onyx/values.yaml) | Stores the `tag` field (e.g., `v7.0.15`) that determines the container image version |
| [`deployment/docker_compose/install.sh`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/docker_compose/install.sh) | Interactive installer that prompts users to select a specific version tag |
| [`cli/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/cli/README.md) | Displays the CI badge linked to [`release-cli.yml`](https://github.com/onyx-dot-app/onyx/blob/main/release-cli.yml), reflecting the latest ODS-managed release status |

## Practical Usage Examples

### Creating a New Release

To cut a new version of Onyx, create and push a semantic version tag:

```bash

# Tag the repository

git tag v8.1.0
git push origin v8.1.0

```

ODS detects the tag automatically and executes the full release pipeline. Alternatively, trigger it manually:

```bash
ods release --tag v8.1.0

```

### Deploying Specific Versions

**Docker Compose:**

The [`install.sh`](https://github.com/onyx-dot-app/onyx/blob/main/install.sh) script in the Docker Compose deployment directory prompts for a version selection:

```bash
cd deployment/docker_compose
./install.sh   # Select "v8.1.0" when prompted

```

**Helm:**

Override the image tag in [`deployment/helm/charts/onyx/values.yaml`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/helm/charts/onyx/values.yaml):

```yaml
image:
  repository: your-registry/onyx
  tag: v8.1.0

```

Then upgrade the release:

```bash
helm upgrade onyx ./deployment/helm/charts/onyx \
  --namespace onyx \
  --set image.tag=v8.1.0

```

### Programmatically Accessing Release Data

Use the utilities module to parse historical release notes for custom integrations or auditing:

```python
from onyx.server.features.release_notes.utils import parse_mdx_to_release_note_entries

# Parse any historical MDX file from the docs directory

entries = parse_mdx_to_release_note_entries(open("docs/release_notes/v7.0.15.mdx").read())
print(f"Release contains {len(entries)} note entries")

```

## Summary

- Onyx uses **Git tags** with a mandatory `v` prefix (e.g., `v7.0.15`) to denote releases rather than a static changelog file
- The **ODS (Onyx Development System)** automates builds, Helm updates, and GitHub releases when tags are pushed
- Release notes are stored as **MDX fragments** parsed by [`backend/onyx/server/features/release_notes/utils.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/release_notes/utils.py)
- Version defaults to **`v0.0.0-dev`** in development environments via [`tools/ods/internal/_version.py`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/_version.py)
- Both **Helm** and **Docker Compose** deployments reference these Git tags to pull the correct container images

## Frequently Asked Questions

### How does Onyx handle version numbers during development?

When building from source without an official tag, the system defaults to `v0.0.0-dev` as defined in [`tools/ods/internal/_version.py`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/internal/_version.py). This ensures development builds are clearly distinguishable from production releases tagged with semantic versions like `v7.0.15`.

### Where can I find the complete Onyx release history?

The definitive release history is stored in the repository's Git tags. Run `git tag -l "v*"` on a cloned copy of `onyx-dot-app/onyx`, or visit the GitHub Releases page. The project does not maintain a `CHANGELOG` file; instead, release details are encoded in MDX fragments within the documentation directory.

### What triggers an automatic Onyx release?

Pushing a Git tag prefixed with `v` (e.g., `v8.1.0`) triggers the ODS automation pipeline. According to [`tools/ods/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/tools/ods/README.md), this initiates image builds, Helm chart updates, and GitHub release publication without requiring manual CI configuration.

### How are release notes generated in Onyx?

Release notes are authored as MDX files and parsed at runtime by the `parse_mdx_to_release_note_entries` function in [`backend/onyx/server/features/release_notes/utils.py`](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/server/features/release_notes/utils.py). These entries are stored as `ReleaseNoteEntry` objects (defined in [`models.py`](https://github.com/onyx-dot-app/onyx/blob/main/models.py)) and served via the backend API to the frontend application.