Skip to main content
This page documents the Palyra release pipeline, focusing on the automated workflow for producing verifiable, portable artifacts for both desktop and headless environments. The release process ensures version coherence across the monorepo, generates multi-platform bundles, and attaches cryptographic provenance for supply chain security.

​
Release Workflow Overview

The release process is driven by the release.yml GitHub Actions workflow. It follows a strict sequence of validation, compilation, packaging, and attestation.

​
1. Version Coherence Assertion

Before any artifacts are built, the workflow executes scripts/release/assert-version-coherence.ps1 to ensure that the version defined in the repository (across 18+ Rust crates and frontend packages) is consistent and matches the git tag being released .github/workflows/release.yml#41-64.

​
2. Multi-Platform Build Matrix

Palyra targets three primary operating systems:

​
3. Artifact Compilation

The workflow builds four core binaries in --release mode:

​
4. Release Engineering Data Flow

The following diagram illustrates how source components are transformed into final portable packages. Package Assembly Data Flow Sources: scripts/release/package-portable.ps1:28-95, scripts/release/validate-portable-archive.ps1:29-57, .github/workflows/release.yml:168-175

​
Portable Package Structures

Palyra distributes two types of portable packages via scripts/release/package-portable.ps1. Both types are designed to be “unzip and run,” requiring no global system installation.

​
Desktop Portable Bundle

Designed for end-user workstations. It includes the graphical supervisor and all necessary sidecars.

​
Headless Portable Package

Designed for servers or remote nodes.

​
Release Manifest & Security Sidecars

Every release includes a release-manifest.json and a checksums.txt file inside the archive to ensure integrity and provide machine-readable metadata.

​
Release Manifest Schema

The manifest is generated by package-portable.ps1 and contains:

​
Supply Chain Security Gates

The release workflow integrates several security layers before publication:
  1. Artifact Attestation: Uses GitHub’s actions/attest-build-provenance to create a cryptographically signed statement of how the artifact was built .github/workflows/release.yml:21-22.
  2. SBOM Generation: cargo cyclonedx generates a Software Bill of Materials in JSON format .github/workflows/security.yml:131-132.
  3. Vulnerability Scanning: Runs cargo audit, cargo deny, and osv-scanner to check for known vulnerabilities in dependencies .github/workflows/security.yml:95-105.
  4. Secret Scanning: gitleaks scans the codebase for accidentally committed credentials .github/workflows/security.yml:120-123.
Security Verification Pipeline Sources: .github/workflows/release.yml:19-23, .github/workflows/security.yml:95-132

​
Installation and Upgrade Implementation

Installation is handled by dedicated PowerShell scripts that validate the portable archives and set up the local environment.

​
Key Installation Functions

​
Upgrade and Migration

Upgrades follow a “replace-and-migrate” pattern. The palyra config migrate command is essential for headless installations. The ROLLBACK.txt included in every package provides explicit steps for reverting to a previous version, emphasizing that the state_root (containing SQLite databases and logs) should remain untouched during binary swaps scripts/release/package-portable.ps1:150-157. Sources: scripts/release/common.ps1:209-246, scripts/release/install-headless-package.ps1:40-112, scripts/release/validate-portable-archive.ps1:94-111, scripts/release/package-portable.ps1:150-157