Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

18.1 KB
Raw Blame

OpenViking Release Guide

This document explains the release goals, version and tag conventions, primary release flows, republishing paths, and verification steps for the OpenViking repository. It is based on the tracked GitHub Actions workflows, build configuration, and package configuration in this repository.

Release Goals

OpenViking does not release a single artifact. A release publishes a set of related assets for different usage paths:

  • openviking Python package: for users who need the local runtime, server, CLI, and full feature set.
  • Python SDK openviking-sdk: for lightweight HTTP clients that call an existing OpenViking server.
  • Microsoft Agent Framework adapter openviking-ms-agent-framework: for MAF applications using an existing OpenViking server.
  • Docker images: for containerized deployments, published to GHCR and Docker Hub.
  • TOS release assets: for source archives, installation scripts, and stable download paths.
  • Rust CLI / npm packages: for users who install the ov CLI through npm.
  • OpenClaw / ClawHub plugin: for OpenClaw plugin distribution.
  • TypeScript SDK @openviking/sdk: for TypeScript and JavaScript HTTP clients.
  • OpenCode plugin @openviking/opencode-plugin: for OpenCode integration distribution.
  • Controlplane MCP mcp-server-openviking-controlplane: MCP server and ov-cp CLI for the control plane.
  • VikingBot: currently distributed through openviking[bot] and the official Docker image; historical standalone release entries are documented separately to avoid misuse.

A formal main-package release should keep the Python package, Docker images, and TOS assets on the same main release tag. SDK, CLI, and ClawHub plugin releases use their own tag or version namespaces.

Version and Tag Conventions

Use the following tag conventions:

Artifact Recommended tag / version Notes
openviking main package vX.Y.Z Main release tag, for example v0.3.26.
openviking-sdk [email protected] SDK-only tag, for example [email protected].
openviking-ms-agent-framework [email protected] Must match the version in integrations/frameworks/microsoft-agent-framework/pyproject.toml.
@openviking/sdk (TypeScript) [email protected] TypeScript SDK tag.
Rust CLI / npm CLI [email protected] CLI-only tag, for example [email protected].
Vika (vika/) [email protected] Must match the version in vika/package.json. See Vika Release Flow.
ClawHub plugin latest YYYY.M.D or YYYY.M.D-N Generated by the workflow or specified manually.
ClawHub plugin dev YYYY.M.D-dev.N Used for the dev channel.

The main package version is resolved from Git tags through setuptools_scm; formal main releases should use vX.Y.Z. The SDK also uses setuptools_scm, but it only matches python-sdk@* tags so it does not conflict with main package tags.

Formal Main Package Release Flow

Formal main package releases go through GitHub Releases in the root repository:

  1. Confirm the release changes are merged into the target branch and PR / main branch checks have passed.
  2. Create a main package tag, for example v0.3.26.
  3. Publish a GitHub Release based on that tag.
  4. The 03. Release workflow runs when the Release is published.
  5. The workflow reuses _Build Distribution to build the sdist and multi-platform wheels.
  6. The workflow publishes the distributions to PyPI.
  7. The workflow builds and pushes multi-architecture Docker images.
  8. The 20. Release TOS Upload workflow uploads the source archive and installation scripts to TOS.

A formal main release publishes to:

  • PyPI: openviking
  • GHCR: ghcr.io/<owner>/<repo>
  • Docker Hub: <dockerhub-user>/openviking
  • TOS: versioned release paths and optional latest stable paths

Manual Main Package Builds, Test Publishing, and Republishing

The root release workflow also supports manual dispatch with these targets:

  • none: build only, without publishing.
  • testpypi: publish to TestPyPI.
  • pypi: publish to PyPI.
  • both: publish to both TestPyPI and PyPI.

If Python distributions were built successfully but publishing failed, use the _Publish Distribution workflow with the relevant build run id. This path is intended for recovery and republishing, not as the normal release entry point.

Docker Image Publishing and Republishing

During a formal main release, Docker images are built and published by the main release workflow. Images are pushed to GHCR and Docker Hub with the release version tag and latest tag.

The repository also provides a standalone Build and Push Docker Image workflow for:

  • Rebuilding an image with a manually specified version.
  • Building images from the main branch.
  • Rebuilding or republishing images after a tag-triggered run.

Note: the standalone Docker workflow currently also runs on v*.*.* tag pushes. The formal GitHub Release source of truth is still the 03. Release workflow; treat the standalone Docker workflow as an image-specific build or republish path to avoid confusing it with the formal release artifact set.

To avoid duplicate publishing, use the main release workflow for formal versions. Use the standalone Docker workflow only for image republishing or special verification.

TOS Release Assets

The TOS release flow creates a source archive and uploads these assets:

  • releases/<tag>/openviking-<tag>-source.zip
  • Claude Code memory plugin install script
  • Codex memory plugin install script
  • Matching TOS install scripts

Formal GitHub Releases trigger the TOS upload automatically and overwrite the stable paths. A manual run takes a tag and uploads its versioned paths; it overwrites the stable paths only with update_latest=true (default false), so repairing an older release's assets does not move users back to that release.

If TOS secrets are not fully configured, the workflow skips uploading and reports it in the step summary without failing the whole workflow.

Memory Plugin Downloads on the Docs Site

The installer and the memory plugins are downloaded from the documentation site, not from the TOS release bucket. Both docs deployments (17. Docs to GitHub Pages at docs.openviking.ai, 19. Docs TOS Deploy to docs.openviking.net) run .github/scripts/build-plugin-downloads.sh and publish its output under /dl, with the same layout as the release bucket: memory-plugin-shared/install.sh and bootstrap.sh, releases/latest/memory-plugin-marketplace.zip, plugins/claude/marketplace.json with plugins/claude/openviking-memory-<plugin version>.zip, plugins/memory-plugins.git, and releases/latest/channels.json, which the install site's version check reads.

They deploy on every push to main that changes the docs, a plugin, the installer or .github/scripts, so a plugin change is published when it is merged, without a tag or a GitHub Release. The published installer reports <date>-<commit> as its version. To publish a plugin fix, merge it with the version bumps that .github/scripts/check-plugin-version-bumps.sh requires; to roll back, revert the change on main and bump the versions again. Both workflows can also be started by hand from main.

The TOS release bucket keeps receiving the same files with each release for installs that still point at it, as described below.

Memory Plugin Hotfix and Rollback on TOS

Installs that point at the TOS release bucket read its stable paths: plugins/claude/marketplace.json (Claude Code), plugins/memory-plugins.git (Codex and TraeCode CLI), releases/latest/memory-plugin-marketplace.zip (every other host), releases/latest/channels.json (install version resolution), and memory-plugin-shared/install.sh and bootstrap.sh. One run of the workflow builds all of them from the commit of the tag it is given.

To publish a plugin hotfix there without a product release:

  1. Merge the fix with the plugin version bumps that .github/scripts/check-plugin-version-bumps.sh requires. Claude Code only updates an installed plugin when its version string changes.
  2. Tag a commit that holds the last release plus the fix, for example on a branch cut from the last vX.Y.Z tag with the fix cherry-picked. Use a tag that does not start with v, such as memory-plugins-YYYY.M.D, and do not publish a GitHub Release for it: v*.*.* tag pushes trigger the Docker workflow, published Releases trigger the main release workflows, and the main package version is resolved from v* tags.
  3. Push the tag and run gh workflow run release-tos.yml -f tag=<tag> -f update_latest=true.

To roll back, run gh workflow run release-tos.yml -f tag=<last good tag> -f update_latest=true. The workflow definition comes from the default branch, but the scripts it calls come from the tag's checkout, so only tags that already contain the current release scripts can be republished; to go back further, publish the older plugin code as a hotfix.

After either run, Claude Code (URL marketplace) picks up the change at its next update check, and a lower version counts as an update. Codex picks it up at its next start, TraeCode CLI on trae-cli plugin marketplace upgrade. Cursor, TRAE, TRAE CN, ZCode, Kimi Code, OpenCode, pi, and Claude Code installs on a local directory marketplace change only when the installer is re-run. dsh installs from npm and is not affected.

Python SDK Release Flow

The Python SDK lives under sdk/python, and its PyPI package name is openviking-sdk. SDK releases use an independent tag namespace:

[email protected]

Typical flow:

  1. Merge SDK-related changes.
  2. Create and push a tag, for example [email protected].
  3. The Python SDK Release workflow runs from the tag.
  4. The workflow resolves the SDK version with setuptools_scm.
  5. The workflow verifies that the current tag equals python-sdk@<resolved-version>.
  6. The workflow builds sdk/python and publishes it to PyPI.

The SDK workflow also supports manual dispatch with testpypi, pypi, or both. Manual dispatch is useful for validation and recovery; formal SDK releases should use [email protected] tags.

Microsoft Agent Framework Release Flow

The adapter lives under integrations/frameworks/microsoft-agent-framework and has an independent version in its pyproject.toml.

  1. Merge the package changes and confirm the integration checks pass.
  2. Run Microsoft Agent Framework Integration Release manually with target testpypi, then verify the published wheel installs and imports.
  3. Create an [email protected] tag on the tested commit and publish a GitHub Release for that tag, with latest disabled (gh release create <tag> --latest=false). The workflow checks that the tag matches the package version, runs the offline contracts, builds the distributions, and publishes to PyPI.

Manual dispatch also supports pypi and both for publishing and recovery. A tag push alone does not start this workflow.

Configure GitHub Trusted Publishers separately on PyPI and TestPyPI for repository volcengine/OpenViking, workflow filename python-agent-framework-release.yml, and environments pypi and testpypi respectively. For the first release, register pending publishers under the package name openviking-ms-agent-framework. Publishing authenticates with OIDC.

Rust CLI / npm Release Flow

The Rust CLI tag format is:

[email protected]

After a cli@* tag is pushed, the Rust CLI Build workflow builds the ov binary for multiple platforms and publishes npm packages:

  • Platform packages: @openviking/cli-linux-x64, @openviking/cli-linux-arm64, @openviking/cli-darwin-x64, @openviking/cli-darwin-arm64, @openviking/cli-win32-x64
  • Wrapper package: @openviking/cli

The workflow injects the version from the tag into the platform packages and wrapper package. If the same version already exists on npm, the workflow skips the already published package.

Vika Release Flow

Vika (vika/) ships as one self-contained archive per platform: linux-x64, linux-arm64, darwin-x64 and darwin-arm64, each with its own Node and dependencies. The Vika Release workflow (vika-release.yml) tests, builds and uploads them to the TOS release bucket under vika/:

  • vika/releases/<version>/: the archives with their .sha256 files, install.sh, and release.json, which is uploaded last. A version is published once: a run stops when a different build of it is uploaded already, while re-running a failed publish job finishes the same build. Publish jobs run one at a time.
  • vika/install.sh and vika/latest: written last, and only by a formal release newer than the current vika/latest. Users install with curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/vika/install.sh | sh, and vika upgrade follows vika/latest. A tag with an older version, such as a hotfix on an earlier line, or with a - in it, such as [email protected], publishes only its own directory; a - version's GitHub Release is marked as a pre-release.

Formal release: set the version in vika/package.json, merge, then push the matching [email protected] tag. The tag must not start with v: v*.*.* tag pushes and Releases of v* tags run the main package workflows. The workflow also creates a GitHub Release for the tag that is not marked as the repository's latest release.

Preview of a branch: run the workflow on that branch, from the Actions page or with gh workflow run vika-release.yml --ref <branch>. It publishes <package version>-<commit> without moving vika/latest, and the run summary shows the install command. Only branches in this repository can be previewed, because publishing needs the TOS secrets.

Pull requests that touch vika/ run the tests and build and check the linux-x64 archive without publishing.

The workflow uses the same TOS secrets as release-tos.yml. The VIKA_DOWNLOAD_BASE and VIKA_TOS_PREFIX repository variables override the public address and the key prefix, for example to rehearse in a fork against a test bucket.

OpenClaw / ClawHub Plugin Release

The OpenClaw plugin is published manually through the OpenViking OpenClaw plugin release workflow. Inputs include:

  • version: optional; when empty, the workflow generates a date-based version.
  • channel: auto, dev, or latest.
  • changelog: release notes for the plugin release.

The workflow resolves the channel and version, packs examples/openclaw-plugin, pushes a generated package branch, and then calls ClawHub's official trusted publishing workflow.

Recommended usage:

  • Use latest or auto for the formal channel.
  • Use dev for development validation.
  • When specifying version manually, ensure it matches the required format for the selected channel.

Other Release Flows

  • TypeScript SDK Release (typescript-sdk-release.yml): triggered by pushing a [email protected] tag, or manually. Publishes @openviking/sdk to npm.
  • Plugin npm Release (plugin-npm-release.yml): runs automatically on pushes to main that touch examples/dsh-memory-plugin/**, examples/opencode-plugin/**, or the shared plugin library examples/memory-plugin-shared/lib/**, or manually. Publishes @openviking/dsh-memory-plugin and @openviking/opencode-plugin to npm, one matrix job per package, and skips versions that already exist.
  • Controlplane MCP Release (controlplane-mcp-release.yml): manual only. Publishes mcp-server-openviking-controlplane, including the ov-cp CLI.

VikingBot Release Notes

VikingBot is no longer maintained as a recommended standalone PyPI release path. The current distribution model is through the main package:

  • Python install entry point: pip install "openviking[bot]".
  • Source development entry point: uv pip install -e ".[bot]".
  • The official Docker image already includes VikingBot by default; disable it with --without-bot or OPENVIKING_WITH_BOT=0.

The former root-level First Release to PyPI workflow has been removed. The current bot/ directory does not contain an independent pyproject.toml, setup.py, or setup.cfg, so it cannot be released as a standalone Python package from this repository.

The file bot/.github/workflows/release.yml lives under the bot subdirectory. Treat it as a historical bot subproject or split-repository release reference, not as a GitHub Actions workflow that the current root repository can directly trigger. Restoring an independent vikingbot package would first require adding standalone Python package metadata, a versioning strategy, and a publishing credential strategy under bot/.

Pre-release Checklist

Before releasing, confirm that:

  • The changes to be released are merged into the target branch.
  • CI / PR checks have passed.
  • The version has not already been published to PyPI, npm, or the Docker registry.
  • The tag name follows the convention for the target artifact.
  • Python dependencies, build configuration, and README files are synchronized.
  • Required secrets or trusted publishing settings are configured for Docker Hub, PyPI/TestPyPI, TOS, npm, and ClawHub.
  • Release notes are ready and document breaking changes, migration steps, and important fixes.

Post-release Verification Checklist

After releasing, verify that:

  • The package version on PyPI / TestPyPI matches the tag.
  • pip install openviking==<version> or pip install openviking-sdk==<version> succeeds.
  • Docker registries contain the version tag and the expected latest / main tag.
  • The multi-architecture Docker manifest can be pulled.
  • TOS versioned paths and stable paths are accessible.
  • npm contains the expected CLI platform packages and wrapper package.
  • The ClawHub plugin channel and version match expectations.

Failure Handling and Republishing Principles

  • PyPI and npm versions generally cannot be overwritten; if package content is wrong, publish a new version.
  • Docker latest, main, and manually specified tags can be rebuilt through the image republishing workflow, but keep released version tags traceable.
  • Treat TOS versioned paths as immutable assets; stable paths may be overwritten through the manual workflow.
  • If build succeeds but publishing fails, prefer the republishing workflow or manual dispatch instead of recreating the same tag with different content.
  • If a tag is wrong, delete and recreate it only if it has not triggered irreversible publishing.