Release Workflow and Orchestration
The release process is triggered via GitHub Actions, either by pushing a version tag (e.g.,v1.2.3) or through a manual workflow_dispatch .github/workflows/release.yml#3-17. The workflow is divided into metadata preparation, multi-platform artifact building, and security validation.
Version Coherence
Before any assets are built, the system asserts that the repository version matches the requested release version usingassert-version-coherence.ps1 .github/workflows/release.yml#45-49. This prevents mismatched binaries from being bundled together.
Release Artifact Pipeline
“Release Pipeline Data Flow” Sources: .github/workflows/release.yml#120-210, scripts/release/package-portable.ps1#1-16, scripts/test/run-cli-install-smoke.ps1#1-6Portable Bundle Creation
Palyra produces two primary artifact kinds:desktop and headless. Packaging is handled by package-portable.ps1, which aggregates binaries, documentation, and the web dashboard into a platform-specific ZIP archive scripts/release/package-portable.ps1#28-36.
Bundle Composition
| Component | Desktop Bundle | Headless Bundle | Source Path |
|---|---|---|---|
palyrad | Yes | Yes | target/release/palyrad |
palyra (CLI) | Yes | Yes | target/release/palyra |
palyra-browserd | Yes | Yes | target/release/palyra-browserd |
desktop-control-center | Yes | No | apps/desktop/src-tauri/target/release/ |
web/ (Dashboard) | Yes | Yes | apps/web/dist |
docs/ (Operator Docs) | Yes | Yes | crates/palyra-cli/data/docs |
Archive Structure and Metadata
Each archive includes arelease-manifest.json containing SHA256 hashes for all included binaries scripts/release/package-portable.ps1#175-185. The packaging script also generates a README.txt with platform-specific installation and update instructions scripts/release/package-portable.ps1#96-148.
Validation and Smoke Testing
Released archives undergo rigorous validation before publication. This ensures that the portable bundles are not only complete but also functional in a clean environment.Portable Archive Validation
Thevalidate-portable-archive.ps1 script performs “Path Traversal” checks and ensures no absolute paths are stored within the ZIP scripts/release/common.ps1#235-245. It also verifies the presence of required documentation files like README.md and release-validation-checklist.md scripts/release/common.ps1#113-121.
Installed Smoke Tests
Therun-cli-install-smoke.ps1 harness simulates a real-world installation:
- Extraction: Unpacks the archive into a temporary
install_rootscripts/release/install-headless-package.ps1#28-29. - Environment Isolation: Sets
PALYRA_STATE_ROOTandPALYRA_CONFIGto temporary directories to avoid polluting the host scripts/test/run-cli-install-smoke.ps1#85-101. - Command Execution: Runs
installed_smoke.rs, which executes the installedpalyrabinary to verifydoctor,setup,config validate, anddocs searchfunctionality crates/palyra-cli/tests/installed_smoke.rs#69-100.
Security, Attestation, and Provenance
Palyra utilizes a multi-layered security gate approach for every release.Build Attestation
The release workflow generates GitHub Build Attestations, providing a cryptographic link between the built artifacts and the source code/workflow that produced them .github/workflows/release.yml:22, 87.Supply Chain Gates
Thesecurity.yml workflow runs before release artifacts are finalized:
- npm audit: Validates the
@palyra/webworkspace against a dev-only allowlist .github/workflows/security.yml#30-63. - Cargo Audit/Deny: Checks Rust dependencies for vulnerabilities and prohibited licenses .github/workflows/security.yml#95-99.
- OSV Scan: Scans the
Cargo.lockagainst the Open Source Vulnerabilities database .github/workflows/security.yml#101-105. - Gitleaks: Scans the entire source tree for accidental secret commits .github/workflows/security.yml#120-123.
- SBOM Generation: Produces a CycloneDX Software Bill of Materials .github/workflows/security.yml#131-133.
Installation and Lifecycle Scripts
Portable releases ship with PowerShell scripts to manage the install/uninstall lifecycle consistently across Windows, macOS, and Linux.install-headless-package.ps1
This script automates the setup of a remote-mode daemon:
- Directory Cleanup: Uses
New-CleanDirectoryto ensure a fresh install scripts/release/install-headless-package.ps1#28. - CLI Exposure: Sets up shims or PATH entries via
Install-PalyraCliExposurescripts/release/install-headless-package.ps1#47-52. - Systemd Integration: On Linux, it generates a
palyrad.serviceunit file with the correctWorkingDirectoryand environment variables scripts/release/install-headless-package.ps1#90-114.
install-desktop-package.ps1
Optimized for the Tauri-based desktop application:
- State Root Isolation: Ensures the
StateRoot(containing databases and logs) is created outside theInstallRootscripts/release/install-desktop-package.ps1#36-40. - Metadata Persistence: Writes
install-metadata.jsonto the install root, recording the installation time and original archive path scripts/release/install-desktop-package.ps1#89-99.
Update and Rollback Guidance
The release includes guidance for upgrades. Headless upgrades require runningpalyra config migrate after binary replacement but before restarting the daemon scripts/release/package-portable.ps1#140-141. Rollbacks involve stopping processes and restoring previous binaries while maintaining the same state root scripts/release/package-portable.ps1#150-156.
Sources: scripts/release/install-headless-package.ps1#1-134, scripts/release/install-desktop-package.ps1#1-111, scripts/release/package-portable.ps1#121-148