release.yml GitHub Action and a suite of PowerShell scripts that manage portable archive creation and validation.
Release Workflow Lifecycle
The release process follows a strict sequence of version coherence checks, multi-platform builds, and automated smoke testing before artifacts are published.1. Metadata Preparation & Coherence
The workflow begins by executingassert-version-coherence.ps1 scripts/release/assert-version-coherence.ps1. This script ensures that the version defined in Cargo.toml matches the requested release tag and any explicit version overrides .github/workflows/release.yml#45-64. It also generates release and migration notes from templates .github/workflows/release.yml#78-106.
2. Artifact Packaging
Palyra distributes two primary artifact types: Desktop Portable Bundles and Headless Portable Packages. Both are managed bypackage-portable.ps1 scripts/release/package-portable.ps1.
| Artifact Kind | Included Components | Target Use Case |
|---|---|---|
| Desktop | palyra-desktop-control-center, palyrad, palyra-browserd, palyra CLI, web/ dist, docs/ | End-user workstations (Windows/macOS/Linux) |
| Headless | palyrad, palyra-browserd, palyra CLI, web/ dist, docs/ | Servers, remote nodes, and CI/CD environments |
3. Validation & Smoke Testing
Before publication, archives are passed tovalidate-portable-archive.ps1 scripts/release/validate-portable-archive.ps1. This script performs:
- Structure Validation: Ensures all required binaries and documentation exist scripts/release/validate-portable-archive.ps1#39-57.
- Hygiene Checks: Scans for forbidden runtime artifacts like
.sqlite,.log, or.walfiles that should never be packaged scripts/release/validate-portable-archive.ps1#59-92. - Checksum Verification: Validates every file against a generated
checksums.txtmanifest scripts/release/validate-portable-archive.ps1#94-121.
Packaging Data Flow
The following diagram illustrates the transformation of build artifacts into a signed release package.Build to Package Pipeline
Sources: scripts/release/package-portable.ps1#65-95, scripts/release/validate-portable-archive.ps1#29-57, .github/workflows/release.yml#165-169Installation & Portable Lifecycle
Palyra uses specialized scripts to handle the “installation” of portable archives, ensuring environment variables and CLI shims are correctly configured.Headless Installation (install-headless-package.ps1)
This script automates the setup of a server environment:
- Extraction: Unpacks the archive to a clean
InstallRootscripts/release/install-headless-package.ps1#28-29. - Configuration: Runs
palyra setupto initialize a remote-mode config at the specifiedConfigPathscripts/release/install-headless-package.ps1#61. - Systemd Integration: On Linux, it generates a
palyrad.serviceunit file pointing to the new binaries and configuration scripts/release/install-headless-package.ps1#88-112. - Verification: Executes a suite of smoke commands (e.g.,
palyra doctor) to ensure the installation is functional scripts/release/install-headless-package.ps1#58-72.
CLI Documentation System
Thepalyra CLI includes a built-in documentation engine that reads from the docs/ directory bundled during packaging.
- Indexing:
build_docs_indexindocs.rsscans the bundled directory to create a searchable index crates/palyra-cli/src/commands/docs.rs#191-212. - Search: The
docs searchcommand allows offline access to migration guides and architectural docs crates/palyra-cli/src/commands/docs.rs#116-158.
Security Attestation & Provenance
Palyra implements a “Security Gates” workflow and GitHub build attestations to provide a verifiable chain of custody for all releases.Build Attestations
The release workflow uses theactions/attest-build-provenance action to generate SLSA (Supply-chain Levels for Software Artifacts) provenance .github/workflows/release.yml#22. These sidecar files allow users to verify that the binaries were indeed built on GitHub’s infrastructure from the specific tag in the marektomas-cz/Palyra repository.
Security Gates
Before a release is finalized, thesecurity.yml workflow enforces several checks:
- Supply Chain:
cargo auditandcargo denycheck for vulnerable or unauthorized dependencies .github/workflows/security.yml#95-99. - SBOM Generation: A Software Bill of Materials is generated using
cargo cyclonedx.github/workflows/security.yml#131-132. - Secret Scanning:
gitleaksscans the repository to prevent accidental credential leakage in the release .github/workflows/security.yml#120-123. - High-Risk Patterns: Custom scripts check for dangerous code patterns and ensure runtime artifacts (like SQLite DBs) are not present in the source tree .github/workflows/security.yml#125-129.
Security Entity Mapping
Sources: .github/workflows/security.yml#95-132, .github/workflows/release.yml#19-22Release Smoke Testing
Therun-release-smoke.ps1 scripts/test/run-release-smoke.ps1 script simulates a full release cycle in a temporary environment. It builds all components, packages them into archives, installs them using the production install scripts, and then verifies that the resulting installation passes all diagnostic checks scripts/test/run-release-smoke.ps1#152-185. This ensures that the install-metadata.json and CLI shims work correctly across different platforms before the actual release is triggered.
Sources: scripts/test/run-release-smoke.ps1#1-185