fix(release): stabilize dev build assets

Author: drew

.github/workflows/release-dev.yml

@@ -30,6 +30,8 @@ jobs:
       python_version: ${{ steps.v.outputs.python }}
       cargo_version: ${{ steps.v.outputs.cargo }}
       deb_version: ${{ steps.v.outputs.deb }}
+      rpm_version: ${{ steps.v.outputs.rpm_version }}
+      rpm_release: ${{ steps.v.outputs.rpm_release }}
     steps:
       - uses: actions/checkout@v6
         with:
@@ -48,6 +50,8 @@ jobs:
           echo "python=$(uv run python tasks/scripts/release.py get-version --python)" >> "$GITHUB_OUTPUT"
           echo "cargo=$(uv run python tasks/scripts/release.py get-version --cargo)" >> "$GITHUB_OUTPUT"
           echo "deb=$(uv run python tasks/scripts/release.py get-version --deb)" >> "$GITHUB_OUTPUT"
+          echo "rpm_version=$(uv run python tasks/scripts/release.py get-version --rpm-version)" >> "$GITHUB_OUTPUT"
+          echo "rpm_release=$(uv run python tasks/scripts/release.py get-version --rpm-release)" >> "$GITHUB_OUTPUT"
 
   build-gateway:
     needs: [compute-versions]
@@ -641,6 +645,10 @@ jobs:
     uses: ./.github/workflows/rpm-package.yml
     with:
       checkout-ref: ${{ github.sha }}
+      rpm-version: ${{ needs.compute-versions.outputs.rpm_version }}
+      rpm-release: ${{ needs.compute-versions.outputs.rpm_release }}
+      cargo-version: ${{ needs.compute-versions.outputs.cargo_version }}
+      python-version: ${{ needs.compute-versions.outputs.python_version }}
     secrets: inherit
 
   # ---------------------------------------------------------------------------
@@ -698,6 +706,31 @@ jobs:
           path: release/
           merge-multiple: true
 
+      - name: Normalize dev package filenames
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+
+          move_one() {
+            local dest="$1"
+            shift
+            local matches=("$@")
+            if [ "${#matches[@]}" -ne 1 ]; then
+              echo "expected exactly one source for ${dest}, found ${#matches[@]}: ${matches[*]-}" >&2
+              exit 1
+            fi
+            mv "${matches[0]}" "release/${dest}"
+          }
+
+          move_one openshell-dev-amd64.deb release/openshell_*_amd64.deb
+          move_one openshell-dev-arm64.deb release/openshell_*_arm64.deb
+          move_one openshell-dev-x86_64.rpm release/openshell-[0-9]*.x86_64.rpm
+          move_one openshell-dev-aarch64.rpm release/openshell-[0-9]*.aarch64.rpm
+          move_one openshell-gateway-dev-x86_64.rpm release/openshell-gateway-[0-9]*.x86_64.rpm
+          move_one openshell-gateway-dev-aarch64.rpm release/openshell-gateway-[0-9]*.aarch64.rpm
+
+          ls -la release/
+
       - name: Capture wheel filenames
         id: wheel_filenames
         run: |
@@ -714,7 +747,7 @@ jobs:
             openshell-x86_64-unknown-linux-musl.tar.gz \
             openshell-aarch64-unknown-linux-musl.tar.gz \
             openshell-aarch64-apple-darwin.tar.gz \
-            openshell_*.deb \
+            *.deb \
             openshell-*.rpm \
             *.whl > openshell-checksums-sha256.txt
           cat openshell-checksums-sha256.txt
@@ -728,20 +761,12 @@ jobs:
             openshell-sandbox-aarch64-unknown-linux-gnu.tar.gz > openshell-sandbox-checksums-sha256.txt
           cat openshell-sandbox-checksums-sha256.txt
 
-      - name: Prune stale wheel, deb, and rpm assets from dev release
+      - name: Prune managed assets from dev release
         uses: actions/github-script@v7
-        env:
-          WHEEL_VERSION: ${{ needs.compute-versions.outputs.python_version }}
         with:
           script: |
-            const wheelVersion = process.env.WHEEL_VERSION;
-            const currentPrefix = `openshell-${wheelVersion}-`;
             const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
 
-            core.info(`=== Wheel pruning diagnostics ===`);
-            core.info(`WHEEL_VERSION: ${wheelVersion}`);
-            core.info(`CURRENT_PREFIX: ${currentPrefix}`);
-
             // Fetch the dev release
             let release;
             try {
@@ -760,27 +785,29 @@ jobs:
               core.info(`  ${String(a.id).padStart(12)}  ${a.name}`);
             }
 
-            // Delete stale wheels, debs, and rpms
-            let kept = 0, deleted = 0, debDeleted = 0, rpmDeleted = 0;
+            const managed = (name) => (
+              name.startsWith('openshell') &&
+              (
+                name.endsWith('.tar.gz') ||
+                name.endsWith('.txt') ||
+                name.endsWith('.whl') ||
+                name.endsWith('.deb') ||
+                name.endsWith('.rpm')
+              )
+            );
+
+            let deleted = 0, skipped = 0;
             for (const asset of assets) {
-              if (asset.name.endsWith('.deb')) {
-                core.info(`Deleting stale deb package: ${asset.name} (id=${asset.id})`);
-                await github.rest.repos.deleteReleaseAsset({ owner, repo, asset_id: asset.id });
-                debDeleted++;
-              } else if (asset.name.endsWith('.rpm')) {
-                core.info(`Deleting stale rpm package: ${asset.name} (id=${asset.id})`);
-                await github.rest.repos.deleteReleaseAsset({ owner, repo, asset_id: asset.id });
-                rpmDeleted++;
-              } else if (asset.name.endsWith('.whl') && asset.name.startsWith(currentPrefix)) {
-                core.info(`Keeping current wheel: ${asset.name}`);
-                kept++;
-              } else if (asset.name.endsWith('.whl')) {
-                core.info(`Deleting stale wheel: ${asset.name} (id=${asset.id})`);
+              if (managed(asset.name)) {
+                core.info(`Deleting managed dev asset: ${asset.name} (id=${asset.id})`);
                 await github.rest.repos.deleteReleaseAsset({ owner, repo, asset_id: asset.id });
                 deleted++;
+              } else {
+                core.info(`Skipping unmanaged asset: ${asset.name}`);
+                skipped++;
               }
             }
-            core.info(`Summary: kept_wheels=${kept}, deleted_wheels=${deleted}, deleted_debs=${debDeleted}, deleted_rpms=${rpmDeleted}`);
+            core.info(`Summary: deleted=${deleted}, skipped=${skipped}`);
 
       - name: Move dev tag
         run: |
@@ -811,7 +838,8 @@ jobs:
             release/openshell-x86_64-unknown-linux-musl.tar.gz
             release/openshell-aarch64-unknown-linux-musl.tar.gz
             release/openshell-aarch64-apple-darwin.tar.gz
-            release/openshell_*.deb
+            release/openshell-dev-amd64.deb
+            release/openshell-dev-arm64.deb
             release/openshell-*.rpm
             release/openshell-gateway-x86_64-unknown-linux-gnu.tar.gz
             release/openshell-gateway-aarch64-unknown-linux-gnu.tar.gz

.github/workflows/release-tag.yml

@@ -41,6 +41,8 @@ jobs:
       python_version: ${{ steps.v.outputs.python }}
       cargo_version: ${{ steps.v.outputs.cargo }}
       deb_version: ${{ steps.v.outputs.deb }}
+      rpm_version: ${{ steps.v.outputs.rpm_version }}
+      rpm_release: ${{ steps.v.outputs.rpm_release }}
       # Semver without 'v' prefix (e.g. 0.6.0), used for image tags and release body
       semver: ${{ steps.v.outputs.semver }}
     steps:
@@ -62,6 +64,8 @@ jobs:
           echo "python=$(uv run python tasks/scripts/release.py get-version --python)" >> "$GITHUB_OUTPUT"
           echo "cargo=$(uv run python tasks/scripts/release.py get-version --cargo)" >> "$GITHUB_OUTPUT"
           echo "deb=$(uv run python tasks/scripts/release.py get-version --deb)" >> "$GITHUB_OUTPUT"
+          echo "rpm_version=$(uv run python tasks/scripts/release.py get-version --rpm-version)" >> "$GITHUB_OUTPUT"
+          echo "rpm_release=$(uv run python tasks/scripts/release.py get-version --rpm-release)" >> "$GITHUB_OUTPUT"
           echo "semver=${RELEASE_TAG#v}" >> "$GITHUB_OUTPUT"
 
   build-gateway:
@@ -668,6 +672,10 @@ jobs:
     uses: ./.github/workflows/rpm-package.yml
     with:
       checkout-ref: ${{ inputs.tag || github.ref }}
+      rpm-version: ${{ needs.compute-versions.outputs.rpm_version }}
+      rpm-release: ${{ needs.compute-versions.outputs.rpm_release }}
+      cargo-version: ${{ needs.compute-versions.outputs.cargo_version }}
+      python-version: ${{ needs.compute-versions.outputs.python_version }}
     secrets: inherit
 
   # ---------------------------------------------------------------------------

.github/workflows/rpm-package.yml

@@ -9,6 +9,22 @@ on:
       checkout-ref:
         required: true
         type: string
+      rpm-version:
+        required: false
+        type: string
+        default: ""
+      rpm-release:
+        required: false
+        type: string
+        default: ""
+      cargo-version:
+        required: false
+        type: string
+        default: ""
+      python-version:
+        required: false
+        type: string
+        default: ""
 
 permissions:
   contents: read
@@ -53,6 +69,11 @@ jobs:
         run: git fetch --tags --force
 
       - name: Build RPMs via Packit
+        env:
+          OPENSHELL_RPM_VERSION: ${{ inputs['rpm-version'] }}
+          OPENSHELL_RPM_RELEASE: ${{ inputs['rpm-release'] }}
+          OPENSHELL_CARGO_VERSION: ${{ inputs['cargo-version'] }}
+          OPENSHELL_PYTHON_VERSION: ${{ inputs['python-version'] }}
         run: packit build locally
 
       - name: Collect RPM artifacts

.packit.yaml

@@ -17,8 +17,10 @@ srpm_build_deps:
 
 actions:
   get-current-version:
-    # Derive version from the latest upstream tag on the current branch.
-    - 'bash -c "git describe --tags --match ''v*'' --abbrev=0 HEAD | sed ''s/^v//''"'
+    # Release workflows pass OPENSHELL_RPM_VERSION so every artifact shares one
+    # precomputed identity. Local Packit runs fall back to the latest semantic
+    # upstream tag on the current branch.
+    - 'bash -c "if [ -n \"${OPENSHELL_RPM_VERSION:-}\" ]; then echo \"${OPENSHELL_RPM_VERSION}\"; else git describe --tags --match ''v[0-9]*.[0-9]*.[0-9]*'' --abbrev=0 HEAD | sed ''s/^v//''; fi"'
 
   create-archive:
     # Step 1: Create source tarball from git working tree.
@@ -38,7 +40,10 @@ actions:
     # Update Version
     - 'bash -c "sed -i -r \"s/^Version:(\\s*)\\S+/Version:\\1${PACKIT_RPMSPEC_VERSION}/\" openshell.spec"'
     # Update Release
-    - 'bash -c "sed -i -r \"s/^Release:(\\s*)\\S+/Release:\\1${PACKIT_RPMSPEC_RELEASE}%{?dist}/\" openshell.spec"'
+    - 'bash -c "RELEASE=${OPENSHELL_RPM_RELEASE:-${PACKIT_RPMSPEC_RELEASE}} && sed -i -r \"s/^Release:(\\s*)\\S+/Release:\\1${RELEASE}%{?dist}/\" openshell.spec"'
+    # Keep embedded binary / Python metadata aligned with the release workflow.
+    - 'bash -c "if [ -n \"${OPENSHELL_CARGO_VERSION:-}\" ]; then sed -i -r \"s/^%global openshell_cargo_version .*/%global openshell_cargo_version ${OPENSHELL_CARGO_VERSION}/\" openshell.spec; fi"'
+    - 'bash -c "if [ -n \"${OPENSHELL_PYTHON_VERSION:-}\" ]; then sed -i -r \"s/^%global openshell_python_version .*/%global openshell_python_version ${OPENSHELL_PYTHON_VERSION}/\" openshell.spec; fi"'
 
 jobs:
   # Build on every pull request targeting main for CI validation

architecture/build-containers.md

@@ -66,6 +66,22 @@ OpenShell also publishes Python wheels for `linux/amd64`, `linux/arm64`, and mac
 - Release workflows mirror the CLI layout: a Linux matrix job for amd64/arm64, a separate macOS job, and release jobs that download the per-platform wheel artifacts directly before publishing.
 - Release CPU jobs run on `linux-amd64-cpu8` and `linux-arm64-cpu8`; the macOS wheel is still cross-compiled in Docker from the amd64 Linux runner.
 
+## Development Release Assets
+
+The rolling `dev` release is installer-facing but still publishes the full
+artifact set: CLI tarballs, standalone gateway and sandbox tarballs, Python
+wheels, Debian packages, RPM packages, and checksums. Every artifact is built
+from the version computed once in `release-dev.yml`.
+
+Package-manager artifacts use stable dev aliases on the GitHub release
+(`openshell-dev-*.deb`, `openshell-dev-*.rpm`, and
+`openshell-gateway-dev-*.rpm`) so the rolling release stays readable. Python
+wheels keep their versioned filenames because wheel metadata requires it.
+
+The dev release workflow prunes workflow-owned `openshell*` assets before
+uploading the fresh set. `openshell-driver-vm` artifacts are intentionally not
+published on the main `dev` release; VM driver binaries live on `vm-dev`.
+
 ## Sandbox Images
 
 Sandbox images are not built in this repository. They are maintained in the [openshell-community](https://github.com/nvidia/openshell-community) repository and pulled from `ghcr.io/nvidia/openshell-community/sandboxes/` at runtime.

architecture/custom-vm-runtime.md

@@ -321,6 +321,10 @@ run `cargo build --release -p openshell-driver-vm`. The macOS driver is
 cross-compiled via osxcross (no macOS runner needed for the binary build —
 only for the kernel build).
 
+`openshell-driver-vm` release assets stay on `vm-dev`. The main rolling `dev`
+release prunes stale VM driver tarballs if they appear there, but does not
+publish new ones.
+
 macOS driver binaries produced via osxcross are not codesigned. Development
 builds are signed automatically by `tasks/scripts/gateway-vm.sh`
 (registered as `mise run gateway:vm`); a packaged release needs signing in

openshell.spec

@@ -2,6 +2,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 %global crate openshell
+%global openshell_cargo_version %{version}
+%global openshell_python_version %{version}
 
 # Cargo/Rust builds with vendored deps do not produce debugsource listings
 # in the format redhat-rpm-config expects (especially on EPEL).
@@ -87,9 +89,9 @@ management, agent execution, and inference routing via gRPC.
 tar xf %{SOURCE1}
 %cargo_prep -v vendor
 
-# Patch workspace version from placeholder to actual version
-sed -i 's/^version = "0.0.0"/version = "%{version}"/' Cargo.toml
-grep -q 'version = "%{version}"' Cargo.toml || (echo "ERROR: Cargo.toml version patch failed" && exit 1)
+# Patch workspace version from placeholder to actual build identity.
+sed -i 's/^version = "0.0.0"/version = "%{openshell_cargo_version}"/' Cargo.toml
+grep -q 'version = "%{openshell_cargo_version}"' Cargo.toml || (echo "ERROR: Cargo.toml version patch failed" && exit 1)
 
 %build
 # Build the CLI and gateway binaries
@@ -203,11 +205,11 @@ install -pm 0644 python/%{name}/_proto/__init__.py %{buildroot}%{python3_sitelib
 install -pm 0644 python/%{name}/_proto/*.py %{buildroot}%{python3_sitelib}/%{name}/_proto/
 
 # Create dist-info so importlib.metadata can resolve the package version
-install -d %{buildroot}%{python3_sitelib}/%{name}-%{version}.dist-info
-cat > %{buildroot}%{python3_sitelib}/%{name}-%{version}.dist-info/METADATA << EOF
+install -d %{buildroot}%{python3_sitelib}/%{name}-%{openshell_python_version}.dist-info
+cat > %{buildroot}%{python3_sitelib}/%{name}-%{openshell_python_version}.dist-info/METADATA << EOF
 Metadata-Version: 2.1
 Name: %{name}
-Version: 0.0.37
+Version: %{openshell_python_version}
 Summary: OpenShell Python SDK for agent execution and management
 License: Apache-2.0
 Requires-Python: >=3.12
@@ -217,10 +219,10 @@ Requires-Dist: protobuf>=4.25
 EOF
 
 # INSTALLER marker per PEP 376
-echo "rpm" > %{buildroot}%{python3_sitelib}/%{name}-%{version}.dist-info/INSTALLER
+echo "rpm" > %{buildroot}%{python3_sitelib}/%{name}-%{openshell_python_version}.dist-info/INSTALLER
 
 # RECORD can be empty for RPM-managed installs
-touch %{buildroot}%{python3_sitelib}/%{name}-%{version}.dist-info/RECORD
+touch %{buildroot}%{python3_sitelib}/%{name}-%{openshell_python_version}.dist-info/RECORD
 
 %check
 # Smoke-test the CLI binary
@@ -233,7 +235,7 @@ touch %{buildroot}%{python3_sitelib}/%{name}-%{version}.dist-info/RECORD
 # We query the dist-info directly rather than importing the package because
 # the full import pulls in grpcio and other runtime deps not present in the
 # build environment.
-PYTHONPATH=%{buildroot}%{python3_sitelib} %{python3} -c "from importlib.metadata import version; v = version('openshell'); print(v); assert v == '%{version}', f'expected %{version}, got {v}'"
+PYTHONPATH=%{buildroot}%{python3_sitelib} %{python3} -c "from importlib.metadata import version; v = version('openshell'); print(v); assert v == '%{openshell_python_version}', f'expected %{openshell_python_version}, got {v}'"
 
 %post gateway
 %systemd_user_post %{name}-gateway.service
@@ -269,7 +271,7 @@ PYTHONPATH=%{buildroot}%{python3_sitelib} %{python3} -c "from importlib.metadata
 %files -n python3-%{name}
 %license LICENSE
 %{python3_sitelib}/%{name}/
-%{python3_sitelib}/%{name}-%{version}.dist-info/
+%{python3_sitelib}/%{name}-%{openshell_python_version}.dist-info/
 
 %changelog
 %autochangelog

python/release_tooling_test.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+
+def _load_release_module():
+    path = Path(__file__).resolve().parents[1] / "tasks/scripts/release.py"
+    spec = importlib.util.spec_from_file_location("openshell_release_tooling", path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+release = _load_release_module()
+
+
+def test_exact_tag_versions_are_stable_release_versions() -> None:
+    versions = release._versions_from_parts((0, 0, 37), 0, "152d05940", "v0.0.37")
+
+    assert versions.python == "0.0.37"
+    assert versions.cargo == "0.0.37"
+    assert versions.docker == "0.0.37"
+    assert versions.deb == "0.0.37-1"
+    assert versions.rpm_version == "0.0.37"
+    assert versions.rpm_release == "1"
+
+
+def test_dev_versions_share_one_build_identity() -> None:
+    versions = release._versions_from_parts((0, 0, 37), 108, "152d05940", "v0.0.37")
+
+    assert versions.python == "0.0.38.dev108+g152d05940"
+    assert versions.cargo == "0.0.38-dev.108+g152d05940"
+    assert versions.docker == "0.0.38-dev.108-g152d05940"
+    assert versions.deb == "0.0.38~dev.108+g152d05940-1"
+    assert versions.rpm_version == "0.0.38"
+    assert versions.rpm_release == "0.dev.108.g152d05940"
+
+
+def test_semver_tag_parser_excludes_vm_tags() -> None:
+    assert release._parse_semver_tag("v0.0.37") == (0, 0, 37)
+    assert release._parse_semver_tag("0.0.37") == (0, 0, 37)
+    assert release._parse_semver_tag("vm-runtime") is None
+    assert release._parse_semver_tag("vm-dev") is None