Workflow Orchestration
The primary entry point for continuous integration isci.yml, which executes on every pull request and push to the main branch .github/workflows/ci.yml#3-7. It defines a matrix of operating systems (ubuntu-latest, macos-latest, windows-latest) to ensure compatibility across the three primary target platforms .github/workflows/ci.yml#22-23.
Pipeline Stages
| Stage | Description | Key Commands/Scripts |
|---|---|---|
| Quality | Enforces formatting, linting, and artifact hygiene. | cargo fmt, cargo clippy, vp check .github/workflows/ci.yml#204-211 |
| Build & Test | Standard compilation and unit testing across the OS matrix. | cargo build, cargo test .github/workflows/ci.yml#45-50 |
| Deterministic Core | Executes high-fidelity integration tests with pinned fixtures. | run-deterministic-core.sh .github/workflows/ci.yml#121 |
| Workflow Regression | Validates complex state machine transitions and CLI flows. | run-workflow-regression.sh .github/workflows/ci.yml#136 |
| CLI Parity | Ensures the CLI command tree matches the defined parity matrix. | render_cli_parity_report .github/workflows/ci.yml#226 |
Deterministic Test Suites
Palyra utilizes deterministic test suites to prevent flakiness in complex subsystems like the gRPC gateway and session orchestrator. These tests rely on pinned fixtures and fake adapters to simulate external dependencies.Core Suite (run-deterministic-core.ps1)
This suite targets critical path logic in the daemon and desktop applications:
- State Initialization: Validates that
state_file_initialization_seeds_onboarding_defaultscreates correct initial conditions scripts/test/run-deterministic-core.ps1#17. - Gateway gRPC: Tests
grpc_route_message_with_fake_adapter_emits_reply_and_journal_eventsto ensure the message pipeline correctly updates theJournalStorescripts/test/run-deterministic-core.ps1#26-27. - Web Integration: Uses
npm run web:testto validate theConsoleApiClientagainst expected backend responses scripts/test/run-deterministic-core.ps1#30-35.
Soak Suite (run-deterministic-soak.sh)
Designed to detect stability issues over repeated cycles:
- Connector Stability:
gateway_envelope_reconnect_resume_cycles_remain_stable_under_soaktests the Discord connector’s resilience scripts/test/run-deterministic-soak.sh#37. - Accounting Integrity:
repeated_dead_letter_recovery_cycles_keep_queue_accounting_stableensures theConnectorSupervisordoesn’t leak state scripts/test/run-deterministic-soak.sh#38.
CLI Parity and Regression Matrix
The CLI serves as the primary interface for many users, necessitating strict command structure enforcement.CLI Parity Acceptance
CI runs an example utilityrender_cli_parity_report which compares the current CLI implementation against cli_parity_matrix.toml .github/workflows/ci.yml#226. This ensures that every command documented in the spec is implemented and that its help output remains consistent via help_snapshots .github/workflows/ci.yml#229.
Workflow Regression Matrix
Therun-workflow-regression.sh script executes complex multi-step scenarios, such as:
- Session Compaction:
session_compaction_apply_persists_durable_writes_and_quality_gatesvalidates that the Phase 4 compaction logic correctly updates theJournalStorescripts/test/run-workflow-regression.sh#46. - ACP Shim:
cli_v1_acp_shimensures the Agent Control Protocol bridge maintains protocol compatibility scripts/test/run-workflow-regression.sh#49.
Security Gates and Hygiene
Thesecurity.yml workflow implements a “Defense in Depth” approach to the supply chain and runtime artifacts .github/workflows/security.yml#1-12.
Supply Chain Validation
- Rust Auditing: Uses
cargo auditto check for CVEs in the dependency graph andcargo denyto enforce license policies and ban unauthorized crates .github/workflows/security.yml#95-99. - NPM Auditing: Runs
npm auditwith a customvalidate-npm-audit-dev-allowlist.mjsscript. This allows the team to explicitly acknowledge vulnerabilities indevDependencieswhile blocking any “High” or “Critical” issues in runtime dependencies .github/workflows/security.yml#30-64. - SBOM Generation: Produces a Software Bill of Materials in CycloneDX format using
cargo cyclonedx.github/workflows/security.yml#131-132.
Static Analysis and Secret Scanning
- Gitleaks: Scans the repository for committed secrets using SARIF reporting .github/workflows/security.yml#120-123.
- CodeQL: Performs deep semantic analysis of the Rust and TypeScript codebases to identify patterns like SSRF or unsafe memory usage .github/workflows/codeql.yml#19-48.
- High-Risk Pattern Scan: A custom
check-high-risk-patterns.shscript looks for prohibited code patterns (e.g., hardcoded credentials or bypassed security checks) .github/workflows/security.yml#128-129.
Artifact Hygiene
The pipeline enforces strict rules on what can be checked into the repository:- GitHub Actions Pinning:
check-gh-actions-pinned.shensures all actions use a full SHA instead of a mutable tag .github/workflows/ci.yml#179-180. - No Vendored Artifacts:
check-no-vendored-artifacts.shprevents binary blobs from being committed .github/workflows/ci.yml#182-183.
Install and Release Smoke Tests
Before a release is finalized, therelease.yml workflow triggers an extensive smoke test to ensure the portable packages are functional.
CLI Install Smoke
Therun-cli-install-smoke.ps1 script creates a clean-room environment to test the installed binary scripts/test/run-cli-install-smoke.ps1#41-83.
- Scenario Context: It sets up isolated directories for
PALYRA_CONFIG,PALYRA_STATE_ROOT, andPALYRA_VAULT_DIRscripts/test/run-cli-install-smoke.ps1#91-101. - Baseline Commands: Validates that the installed binary can execute
version,doctor, andprotocol versioncrates/palyra-cli/tests/installed_smoke.rs#69-84. - Lifecycle Flows: Tests non-interactive
setupandonboarding wizardflows to ensure the application can be bootstrapped from scratch crates/palyra-cli/tests/installed_smoke.rs#151-194.
Version Coherence
Theassert-version-coherence.ps1 script is called during the release preparation to ensure that all 18 crates in the workspace share the exact same version string, preventing partial or mismatched releases .github/workflows/release.yml#45.
Sources: scripts/test/run-cli-install-smoke.ps1#1-101, crates/palyra-cli/tests/installed_smoke.rs#1-194, .github/workflows/release.yml#29-65