Skip to main content
The Palyra release pipeline is responsible for transforming the monorepo source into verifiable, portable distribution artifacts. It ensures version coherence across all crates, bundles the desktop and headless environments, and generates security attestations (SHA256, SBOM, and SLSA provenance).

​
Release Pipeline Overview

The release process is orchestrated via GitHub Actions and a suite of PowerShell scripts that provide cross-platform parity for packaging logic. The pipeline validates that the system is in a “release-ready” state by performing strict version checks and running a dedicated “release smoke” suite against the packaged artifacts.

​
Version Coherence

Before any artifact is built, the pipeline runs assert-version-coherence.ps1 to ensure that all internal crates and applications share the same version string [.github/workflows/release.yml#45-49](http://.github/workflows/release.yml#45-49). This prevents partial releases where the CLI might report a different version than the daemon it supervises.

​
Packaging Flow Diagram

The following diagram illustrates the flow from source binaries to the final portable bundles. Figure 1: Packaging Data Flow Sources: [.github/workflows/release.yml#165-175](http://.github/workflows/release.yml#165-175), [scripts/release/package-portable.ps1#84-95](http://scripts/release/package-portable.ps1#84-95)

​
Portable Distribution Bundles

Palyra distributes two primary artifact kinds: desktop and headless. Both are designed to be “portable,” meaning they do not require a system-wide installer and can run from any directory provided their internal structure is maintained.

​
1. Desktop Portable Bundle

The desktop bundle is a superset of the headless package, adding the Tauri-based Control Center.
  • Contents: palyra-desktop-control-center, palyrad, palyra-browserd, palyra (CLI), and the web/ dashboard bundle [scripts/release/package-portable.ps1#84-95](http://scripts/release/package-portable.ps1#84-95).
  • Target Platforms: Windows (x64), macOS (x64/arm64), and Linux (x64) [.github/workflows/release.yml#127-128](http://.github/workflows/release.yml#127-128).

​
2. Headless Portable Package

Designed for server or remote node deployments.
  • Contents: palyrad, palyra-browserd, palyra (CLI), and the web/ dashboard bundle [scripts/release/package-portable.ps1#87-95](http://scripts/release/package-portable.ps1#87-95).
  • Systemd Integration: The headless installer install-headless-package.ps1 automatically generates a palyrad.service unit file to facilitate daemonization on Linux [scripts/release/install-headless-package.ps1#88-112](http://scripts/release/install-headless-package.ps1#88-112).

​
Internal Bundle Structure

Both bundles follow a strict layout required for the palyra-cli to locate its companion services and documentation:
PathDescription
/palyraThe CLI entry point (palyra.exe on Windows)
/palyradThe Core Daemon
/palyra-browserdHeadless Browser Service
/web/Static assets for the Web Console
/docs/Bundled Markdown documentation for offline use
/release-manifest.jsonMetadata about the build (version, platform, kind)
/checksums.txtSHA256 hashes of every file in the bundle
Sources: [scripts/release/package-portable.ps1#91-95](http://scripts/release/package-portable.ps1#91-95), [scripts/release/validate-portable-archive.ps1#29-57](http://scripts/release/validate-portable-archive.ps1#29-57)

​
Installation and Lifecycle Management

Release artifacts are managed via specialized installation scripts that verify the integrity of the archive before extraction.

​
Installation Logic

The scripts install-desktop-package.ps1 and install-headless-package.ps1 perform the following steps:
  1. Validation: Calls validate-portable-archive.ps1 to check the release-manifest.json and verify all file SHA256 hashes [scripts/release/install-desktop-package.ps1#18](http://scripts/release/install-desktop-package.ps1#18).
  2. Extraction: Unpacks the ZIP to the InstallRoot [scripts/release/install-desktop-package.ps1#25](http://scripts/release/install-desktop-package.ps1#25).
  3. CLI Exposure: Registers the palyra command in the user’s environment via Install-PalyraCliExposure [scripts/release/install-desktop-package.ps1#34-37](http://scripts/release/install-desktop-package.ps1#34-37).
  4. Smoke Test: Executes palyra version and palyra doctor to ensure the binaries are compatible with the host OS [scripts/release/install-desktop-package.ps1#53-65](http://scripts/release/install-desktop-package.ps1#53-65).

​
Bundled Documentation

The CLI includes a docs command group (implemented in crates/palyra-cli/src/commands/docs.rs) that allows users to search and view the documentation bundled within the release [crates/palyra-cli/src/commands/docs.rs#74-85](http://crates/palyra-cli/src/commands/docs.rs#74-85). This ensures that migration guides and architecture docs are available even in air-gapped or headless environments. Sources: [scripts/release/install-headless-package.ps1#58-72](http://scripts/release/install-headless-package.ps1#58-72), [crates/palyra-cli/src/commands/docs.rs#11-14](http://crates/palyra-cli/src/commands/docs.rs#11-14)

​
Security and Attestation

Palyra implements a “Security Gate” workflow to protect the supply chain. Every release undergoes scanning and generates cryptographic proof of its origin.

​
Supply Chain Checks

The security.yml workflow runs several audits before a release is finalized:
  • Dependency Audits: npm audit (for the web frontend) and cargo audit / cargo deny (for Rust crates) [.github/workflows/security.yml:30-31, 95-99]().
  • Vulnerability Scanning: Uses osv-scanner to check against the Open Source Vulnerabilities database [.github/workflows/security.yml#101-104](http://.github/workflows/security.yml#101-104).
  • Secret Detection: gitleaks scans the repository to prevent accidental credential leakage [.github/workflows/security.yml#120-123](http://.github/workflows/security.yml#120-123).

​
Artifact Provenance

For every release, the following artifacts are generated:
  • SBOM: A Software Bill of Materials in CycloneDX format using cargo-cyclonedx [.github/workflows/security.yml#131-132](http://.github/workflows/security.yml#131-132).
  • Build Attestations: GitHub SLSA provenance attestations are generated for all uploaded assets, allowing users to verify that the binaries were built on GitHub’s official runners from the tagged source [.github/workflows/release.yml:21-22, 87]().
Figure 2: Security Gate Implementation Sources: [.github/workflows/security.yml:58-63, 128-132]()

​
Release Smoke Testing

The run-release-smoke.ps1 script provides the final validation. It simulates a clean installation from a generated ZIP archive and verifies that all canonical lifecycle surfaces are functional.

​
Verified Surfaces

The smoke test iterates through helpCommands to ensure that aliases and core commands are correctly wired:
  • Setup: palyra setup and the init alias [scripts/test/run-release-smoke.ps1#56-57](http://scripts/test/run-release-smoke.ps1#56-57).
  • Orchestration: palyra gateway and the daemon alias [scripts/test/run-release-smoke.ps1#61-62](http://scripts/test/run-release-smoke.ps1#61-62).
  • Documentation: Verifies that palyra docs search migration returns valid results from the bundled documentation [scripts/test/run-release-smoke.ps1#87](http://scripts/test/run-release-smoke.ps1#87).
  • Maintenance: Runs palyra update --dry-run and palyra uninstall --dry-run to ensure the portable maintenance logic is intact [scripts/test/run-release-smoke.ps1#95-108](http://scripts/test/run-release-smoke.ps1#95-108).
Sources: [scripts/test/run-release-smoke.ps1:55-72, 84-108]()