Release Workflow & Version Coherence
The release process begins with a strictly enforced version coherence check. The system asserts that the repository state matches the intended release version before any packaging occurs.- Metadata Derivation: The
prepare-releasejob in.github/workflows/release.ymlusesscripts/release/assert-version-coherence.ps1to extract and validate the workspace version .github/workflows/release.yml#30-45. - Tag Validation: If triggered by a git tag, the workflow ensures the tag (e.g.,
v1.2.3) matches the internal crate versions exactly .github/workflows/release.yml#51-64. - Note Generation: Release and migration notes are dynamically generated and uploaded as draft assets to the GitHub release .github/workflows/release.yml#78-113.
Portable Bundle Composition
Palyra distributes two primary artifact kinds: Desktop and Headless. Both are packaged as ZIP archives containing a self-contained payload of binaries, web assets, and documentation.Bundle Structure Comparison
| Component | Desktop Bundle | Headless Package |
|---|---|---|
| Control Center | palyra-desktop-control-center | N/A |
| Core Daemon | palyrad | palyrad |
| Browser Service | palyra-browserd | palyra-browserd |
| CLI Entrypoint | palyra | palyra |
| Web Dashboard | web/ (static dist) | web/ (static dist) |
| Operator Docs | docs/ (Markdown) | docs/ (Markdown) |
| Metadata | release-manifest.json | release-manifest.json |
package-portable.ps1 script orchestrates this composition, staging binaries and ensuring that required documentation (README, ROLLBACK, LICENSE) is present scripts/release/package-portable.ps1#28-95.
Code-to-Entity Release Mapping
The following diagram maps release script logic to the physical filesystem entities they produce. Sources: scripts/release/package-portable.ps1#1-148, scripts/release/common.ps1#33-60Integrity & Security Gates
Release artifacts undergo rigorous validation to ensure supply chain security and runtime safety.Manifests & Checksums
Every bundle includes achecksums.txt file containing SHA256 hashes of every file in the payload scripts/release/package-portable.ps1#79-81. The validate-portable-archive.ps1 script performs a mandatory re-calculation of these hashes during the CI smoke test to detect corruption or tampering scripts/release/validate-portable-archive.ps1#94-111.
Security Scanning
Thesecurity.yml workflow executes a comprehensive suite of gates:
- Secret Scanning:
gitleaksdetects committed credentials .github/workflows/security.yml#120-123. - Vulnerability Scanning:
cargo auditandosv-scannercheck for CVEs in Rust dependencies .github/workflows/security.yml#95-104. - Supply Chain:
cargo cyclonedxgenerates a Software Bill of Materials (SBOM) .github/workflows/security.yml#131-133. - SLSA & Attestations: GitHub build attestations and provenance sidecars are generated to provide non-forgeable proof of the build origin .github/workflows/release.yml#19-22.
Installation & Lifecycle Scripts
Portable bundles are managed via specialized installation scripts that handle environment setup, CLI exposure, and service unit generation.Headless Installation Flow
Theinstall-headless-package.ps1 script performs the following:
- Extraction: Unpacks the archive to a clean directory scripts/release/install-headless-package.ps1#28-29.
- CLI Exposure: Creates a shim or symlink for the
palyracommand scripts/release/install-headless-package.ps1#47-50. - Configuration: Invokes
palyra setupto initialize the remote config and validates it scripts/release/install-headless-package.ps1#61-62. - Service Integration: Generates a
systemdunit file forpalyradon Linux systems scripts/release/install-headless-package.ps1#88-112.
Release Smoke Testing
Before a release is finalized, therun-release-smoke.ps1 script executes a full lifecycle test:
- Installs both Desktop and Headless bundles to temporary roots scripts/test/run-release-smoke.ps1#178-183.
- Verifies that
palyraresolves from the expected path scripts/test/run-release-smoke.ps1#53. - Executes
palyra doctorandpalyra docs searchto ensure bundled resources are accessible scripts/test/run-release-smoke.ps1#86-91. - Performs dry-run updates and uninstalls scripts/test/run-release-smoke.ps1#95-108.
Lifecycle Entity Interaction
The following diagram illustrates how installation scripts interact with system components and the CLI. Sources: scripts/release/install-headless-package.ps1#1-132, scripts/test/run-release-smoke.ps1#1-123Bundled Documentation (Offline Docs)
The CLI provides adocs command family that operates on the Markdown files packaged within the bundle’s docs/ directory crates/palyra-cli/src/commands/docs.rs#11-14.
- Indexing: The CLI builds an in-memory index of all bundled
.mdand help snapshot.txtfiles crates/palyra-cli/src/commands/docs.rs#191-212. - Search: Users can search offline documentation via
palyra docs search <query>crates/palyra-cli/src/commands/docs.rs#116-158. - Snapshots: CLI help text is versioned as snapshots in
docs/help_snapshots/to ensure help content is accurate for the specific release build crates/palyra-cli/src/commands/docs.rs#13-14.