CI Pipeline Overview (ci.yml)
The primary CI pipeline is defined in .github/workflows/ci.yml. it executes on every pull request and on pushes to the main branch .github/workflows/ci.yml#3-7. The pipeline is partitioned into several specialized jobs to balance speed and thoroughness.
Build and Test Matrix
The corebuild-and-test job utilizes a strategy matrix across ubuntu-latest, macos-latest, and windows-latest .github/workflows/ci.yml#18-23. This ensures that platform-specific code (such as the palyra-vault DesktopSecretStore or palyra-identity filesystem interactions) is validated in its native environment.
Specialized Quality Gates
Beyond standard compilation, the pipeline enforces several strict quality gates:| Job | Purpose | Tools/Scripts |
|---|---|---|
deterministic-core | Validates the core state machine and journal store without side effects. | scripts/test/run-deterministic-core.sh .github/workflows/ci.yml#89-121 |
workflow-regression | Runs a matrix of automated agent workflows to detect logic regressions. | scripts/test/run-workflow-regression.sh .github/workflows/ci.yml#123-136 |
quality | Enforces linting, formatting, and repository hygiene. | clippy, rustfmt, scripts/check-gh-actions-pinned.sh .github/workflows/ci.yml#172-211 |
cli-parity | Validates that CLI commands match the expected capability matrix. | render_cli_parity_report example .github/workflows/ci.yml#213-226 |
Data Flow: CI Build Process
The following diagram illustrates the flow from code submission to artifact readiness within the CI environment. CI Execution Flow Sources: .github/workflows/ci.yml#16-212, .github/actions/setup-vp-safe/action.yml#1-42Security Gates (security.yml)
The security pipeline (.github/workflows/security.yml) acts as a hardened gate for supply chain integrity and secret prevention. It is invoked via workflow_call or manual dispatch .github/workflows/security.yml#3-5.
Supply Chain Scanning
Palyra employs a multi-layered approach to dependency security:- Cargo Audit: Checks
Cargo.lockagainst the Advisory Database for vulnerable Rust crates .github/workflows/security.yml#95-96. - Cargo Deny: Enforces license compliance and bans specific “risky” dependency trees .github/workflows/security.yml#98-99.
- OSV Scanner: Uses Google’s OSV database to find vulnerabilities in both Rust and NPM dependencies .github/workflows/security.yml#101-104.
- NPM Audit & Allowlist: Validates the
apps/webworkspace. It uses a custom validator to allow specific dev-only advisories that are deemed low-risk for the production bundle .github/workflows/security.yml#30-63.
Secret Detection and Static Analysis
- Gitleaks: Scans the entire repository history for committed secrets, using a SARIF report format for GitHub Security integration .github/workflows/security.yml#120-123.
- High-Risk Pattern Scan: A custom script (
scripts/check-high-risk-patterns.sh) that searches for dangerous code patterns (e.g., unsafe FFI without wrappers) .github/workflows/security.yml#128-129. - CodeQL: Performs deep semantic analysis of the Rust and JavaScript/TypeScript codebases, scheduled weekly or on PRs .github/workflows/codeql.yml#1-48.
SBOM and Attestation
The pipeline generates a Software Bill of Materials (SBOM) in CycloneDX JSON format usingcargo-cyclonedx .github/workflows/security.yml#131-132. This artifact provides a machine-readable inventory of all components included in the build.
Security Tooling and Entity Mapping
Sources: .github/workflows/security.yml#30-132, scripts/validate-npm-audit-dev-allowlist.mjs#1-31
Custom Security Controls
Downstream Patch Governance
In rare cases where an upstream dependency has a vulnerability (e.g.,glib UB in VariantStrIter) that cannot be immediately updated due to transitives, Palyra uses a “Downstream Patch” mechanism SECURITY.md#51-65.
The check-desktop-glib-patch.sh script enforces the following:
- The patched crate must be vendored in
third_party/apps/desktop/src-tauri/docs/security/advisories/GHSA-wrw7-89jp-8q8g.md#27-30. - The
Cargo.tomlmust use a[patch.crates-io]directive apps/desktop/src-tauri/docs/security/advisories/GHSA-wrw7-89jp-8q8g.md#32-33. - A governance file (
PALYRA_PATCH_GOVERNANCE.env) must exist with a valid owner and checksum apps/desktop/src-tauri/docs/security/advisories/GHSA-wrw7-89jp-8q8g.md#47-53.
The setup-vp-safe Action
Located at .github/actions/setup-vp-safe/action.yml, this composite action standardizes the environment for all CI jobs. It ensures:
- Node.js Installation: Pinned via
.node-version.github/actions/setup-vp-safe/action.yml#20-33. - Vite+ CLI: Bootstrapped via
scripts/ci/ensure-vp.ps1to provide thevpcommand .github/actions/setup-vp-safe/action.yml#34-36. - Workspace Integrity: Runs
vp installto guarantee deterministic dependency resolution across the monorepo .github/actions/setup-vp-safe/action.yml#38-41.