Skip to main content
The Palyra CI/CD infrastructure is designed to enforce rigorous quality gates across a multi-platform Rust and TypeScript monorepo. It ensures protocol stability, CLI parity, and supply chain security through a tiered execution model involving GitHub Actions, local just workflows, and specialized smoke test harnesses.

​
CI Workflow Architecture

The primary CI pipeline is defined in .github/workflows/ci.yml, which orchestrates building and testing across a matrix of ubuntu-latest, macos-latest, and windows-latest .github/workflows/ci.yml#18-23.

​
Build and Test Matrix

The core build-and-test job performs the following sequence:
  1. Environment Setup: Installs the pinned Rust toolchain (1.91.0) with rustfmt and clippy .github/workflows/ci.yml#28-32.
  2. JS Workspace: Uses the setup-vp-safe action to initialize the vp workspace orchestrator .github/workflows/ci.yml#34-39.
  3. UI Preparation: Ensures the desktop UI is built before Rust compilation to satisfy tauri build requirements .github/workflows/ci.yml#41-44.
  4. Compilation: Executes cargo build --workspace --locked to ensure reproducible builds .github/workflows/ci.yml#45-46.
  5. Test Execution: Runs the full workspace test suite .github/workflows/ci.yml#48-49.

​
Deterministic and Regression Suites

Beyond standard unit tests, the CI includes specialized jobs for system-level stability:
  • Deterministic Core: Runs scripts/test/run-deterministic-core.sh to validate state transitions in the daemon without network jitter .github/workflows/ci.yml#120-121.
  • Workflow Regression: Executes scripts/test/run-workflow-regression.sh, which exercises end-to-end scenarios like setup, backup, and restore .github/workflows/ci.yml#135-136.
  • Performance Smoke: Validates that core operations remain within defined latency budgets via scripts/test/run-performance-smoke.sh .github/workflows/ci.yml#169-170.
Sources: .github/workflows/ci.yml#1-172, justfile#47-87

​
Quality Gates and Linting

Quality gates are enforced in the quality and cli-parity jobs to maintain codebase health and CLI consistency.

​
Static Analysis and Formatting

​
CLI Parity Acceptance

A unique quality gate ensures that the CLI remains consistent across platforms. The cli-parity job generates a report using the render_cli_parity_report example against cli_parity_matrix.toml .github/workflows/ci.yml#225-227. It validates that all commands have corresponding help snapshots and parity tests .github/workflows/ci.yml#228-230.

​
Quality Gate Data Flow

The following diagram illustrates how local developer actions translate into CI quality gates. CI Quality Gate Pipeline Sources: .github/workflows/ci.yml#172-236, .githooks/pre-push#1-5, justfile#1-24

​
Security Gates and Supply Chain

Security automation is centralized in .github/workflows/security.yml and is triggered on every PR or as a scheduled task.

​
Supply Chain Validation

  • Cargo Audit/Deny: Uses cargo-audit to check for vulnerabilities in Rust dependencies and cargo-deny to enforce license compliance .github/workflows/security.yml#95-99.
  • NPM Audit with Allowlist: Runs npm audit on the web workspace. A custom script, validate-npm-audit-dev-allowlist.mjs, allows specific high-risk dev-only vulnerabilities that are not reachable at runtime .github/workflows/security.yml#30-64.
  • OSV Scanner: Integrates Google’s osv-scanner to detect vulnerabilities across both Rust and JS ecosystems .github/workflows/security.yml#101-104.

​
Secret and Pattern Scanning

​
Provenance and SBOM

The pipeline generates a Software Bill of Materials (SBOM) in CycloneDX format using cargo cyclonedx .github/workflows/security.yml#131-132. It also produces build attestation placeholders to support SLSA provenance .github/workflows/security.yml#147-148. Sources: .github/workflows/security.yml#1-156, justfile#116-136

​
Protocol and Workspace Orchestration

Palyra uses specialized tools to manage its polyglot nature and strict communication contracts.

​
Protocol Contract Validation

The gRPC and Protobuf definitions are guarded by the protocol task in the justfile. This ensures that generated stubs for Rust, Swift, and Kotlin remain in sync with the .proto definitions justfile#97-107.
  • validate-proto.sh: Checks for breaking changes in the schema justfile#98.
  • generate-stubs.sh: Re-generates client/server code justfile#101.
  • validate-rust-stubs.sh: Ensures the committed Rust code matches the generated output justfile#106.

​
VP Workspace Orchestrator

The vp tool (Vite+) is used to manage the JS-heavy components of the monorepo. It handles dependency installation and linting for apps/web, apps/desktop/ui, and apps/browser-extension .github/workflows/ci.yml#204-205. Sources: justfile#97-107, Makefile#23-32, .github/workflows/ci.yml#198-205

​
CLI Install Smoke Testing

To ensure that the release binaries actually function in diverse environments, the CLI install smoke workflow simulates a fresh installation.

​
Smoke Harness Logic

The harness, implemented in scripts/test/run-cli-install-smoke.ps1, performs the following:
  1. Scenario Context: Creates isolated directories for config, state, and vault to prevent interference with the host system scripts/test/run-cli-install-smoke.ps1#41-83.
  2. Environment Overrides: Sets PALYRA_CONFIG and PALYRA_STATE_ROOT to the temporary paths scripts/test/run-cli-install-smoke.ps1#85-101.
  3. Command Execution: Runs a sequence of commands including setup, doctor, config validate, and update --dry-run crates/palyra-cli/tests/installed_smoke.rs#69-146.

​
Workflow to Code Entity Mapping

The smoke test bridges high-level CLI commands to the underlying test harness entities. Smoke Test Entity Mapping Sources: scripts/test/run-cli-install-smoke.ps1#41-220, crates/palyra-cli/tests/installed_smoke.rs#17-148

​
Pre-Push Hooks

To minimize CI failures, developers are encouraged to use the pre-push hook located at .githooks/pre-push. This script triggers scripts/run-pre-push-checks.sh, which runs a subset of the CI checks locally .githooks/pre-push#1-5. The justfile provides two profiles for these checks:
  • just push-gate-fast: Runs basic linting and unit tests justfile#76-77.
  • just push-gate-full: Runs the complete suite including workflow regressions and deterministic soaks justfile#79-80.
Sources: .githooks/pre-push#1-5, justfile#76-80