Onyx Release History: Semantic Versioning and Automated Deployment

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, 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:

# 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, 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 file, Onxy encodes its release history directly in Git. You can view the complete timeline using standard Git commands:

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 as a valid release tag example
• v7.0.15 – Listed in 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 convert these files into structured ReleaseNoteEntry objects:

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 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	Reads GITHUB_REF_NAME and defaults to v0.0.0-dev for untagged builds
tools/ods/cmd/cherry-pick.go	Handles back-porting commits and normalizes version strings with the v prefix
tools/ods/README.md	Documents the ODS workflow and automatic deployment triggers
backend/onyx/server/features/release_notes/utils.py	Parses MDX release notes into database entries
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	Interactive installer that prompts users to select a specific version tag
cli/README.md	Displays the CI badge linked to 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:

# 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:

ods release --tag v8.1.0

Deploying Specific Versions

Docker Compose:

The install.sh script in the Docker Compose deployment directory prompts for a version selection:

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

Helm:

Override the image tag in deployment/helm/charts/onyx/values.yaml:

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

Then upgrade the release:

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:

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
• Version defaults to v0.0.0-dev in development environments via 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. 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, 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. These entries are stored as ReleaseNoteEntry objects (defined in models.py) and served via the backend API to the frontend application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}