Markdown

Releasing

Pi Dash has two independent release streams:

  1. Runner (pidash binary) — versioned, tag-driven, packaged by cargo-dist. External contract with installed users.
  2. Platform (web + Django) — internal versioning; cloud and self-host follow their own paths.

Runner releases#

Tooling#

  • cargo-dist — orchestrates the build matrix and packaging. Config in dist-workspace.toml.
  • .github/workflows/release.yml — the GitHub Actions workflow triggered by SemVer tags.
  • runner/install.sh / runner/install.ps1 — opinionated wrapper installers (do auto-auth after install).
  • The bare cargo-dist installers (pidash-installer.sh, pidash-installer.ps1, MSI) are also published — used by CI / base images that want to install without auto-auth.

Build matrix#

Each tagged release produces binaries for:

  • macOS arm64 (Apple Silicon)
  • macOS x86_64 (Intel)
  • Linux arm64
  • Linux x86_64
  • Windows x86_64 (zip + MSI)

Plus shell, PowerShell, and MSI installer scripts.

Tag & ship#

# In runner/Cargo.toml, bump version to X.Y.Z, commit.
git tag pidash-vX.Y.Z          # tag prefix matters — workflow filters on it
git push origin pidash-vX.Y.Z

The workflow builds, signs, and publishes to GitHub Releases.

Prereleases#

Tags with a SemVer suffix (-rc.1, -alpha.1, -beta.1) are deliberately excluded from /releases/latest/. The public install one-liners always serve the last stable release. To install a prerelease, use the tag-pinned URL:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/The-AI-Republic/pi-dash/releases/download/pidash-vX.Y.Z-rc.1/install.sh | sh

Announce the release to runners#

The Django backend reads two env vars and folds them into every welcome session response (see 08 — Cloud ↔ runner protocol):

Env varEffect
LATEST_RUNNER_VERSIONDrives the yellow “update available” advisory. With auto-update on (default), triggers in-place binary swap.
MIN_RUNNER_VERSIONDrives the red “update required” advisory.

For stable runner releases, .github/workflows/release.yml automatically writes the tag version to /pidash/config/test/LATEST_RUNNER_VERSION and /pidash/config/prod/LATEST_RUNNER_VERSION in SSM. It does not restart or redeploy the API; running containers pick up the value on their next normal restart/deploy. Leave MIN_RUNNER_VERSION alone unless you’re forcing a floor (e.g. shedding an EOL wire version). Runners with auto-update disabled see a pidash update --restart hint so they can install and apply the release in one command.

For self-hosted or non-Cloud environments, leave both unset to skip the announcement entirely.

In-place updates#

pidash swaps its on-disk binary while running; the running process is never disturbed. The new binary takes effect on the next natural restart (pidash restart, host reboot, service-manager respawn after crash).

pidash update --restart swaps the binary and restarts the daemon in one command. pidash update without --restart only swaps the binary.

pidash update only works for installs done via cargo-dist installers (they leave a receipt). Source builds and cargo install builds get a clear “reinstall via the installer if you want self-update” error.

Platform releases (web + Django)#

The OSS platform (this repo) uses standard SemVer in package.json (currently 1.3.0). The cut process is intentionally lightweight — see RELEASING.md at the repo root for the current procedure.

Pi Dash Cloud (private-pi-dash)#

The hosted Cloud overlay lives in a separate repo. Its release tags are date-based: vYYYY.M.D (no zero-pad), starting from 2026-05-24. Prior cloud releases used SemVer. This OSS repo does not produce those tags.

Versioning summary#

ComponentSchemeWhere tag lives
Runner (pidash)SemVer with pidash-v prefix (e.g. pidash-v0.1.4)This repo
Runner wire protocolInteger (currently 4)runner/src/cloud/protocol.rs
Platform (web + Django)SemVer, root package.jsonThis repo
Cloud overlayDate tags vYYYY.M.Dprivate-pi-dash (separate repo)
  • RELEASING.md at the repo root — current platform release procedure
  • runner/README.md — install one-liners, version pinning recipes, advisory states
  • 08 — Cloud ↔ runner protocol — how the version advisories propagate

Search Docs and Blog