> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Pipelines and Security Gates

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * .githooks/pre-commit
  * .github/codeql/codeql-config.yml
  * .github/workflows/ci.yml
  * .github/workflows/cli-full-regression.yml
  * .github/workflows/cli-install-smoke.yml
  * .github/workflows/codeql.yml
  * .github/workflows/dependency-review\.yml
  * .github/workflows/release.yml
  * .github/workflows/security.yml
  * apps/web/src/chat/ChatConsolePanel.effects.test.tsx
  * apps/web/src/chat/ChatConsoleWorkspaceView\.tsx
  * apps/web/src/chat/starterPrompts.ts
  * apps/web/src/chat/useStarterPromptHandoff.ts
  * apps/web/src/console/hooks/useOverviewDomain.ts
  * scripts/check-architecture-boundaries.sh
  * scripts/check-english-source.sh
  * scripts/check-local-only-tracked-files.sh
  * scripts/ci/changed-scope-map.tsv
  * scripts/ci/plan-changed-scope.sh
  * scripts/dev/module-budget-allowlist.txt
  * scripts/dev/report-module-budgets.sh
  * scripts/run-pre-push-checks.sh
  * scripts/test/check-runtime-contract-snapshots.ps1
  * scripts/test/check-runtime-contract-snapshots.sh
</details>

This page details the Palyra CI/CD infrastructure, the automated security software development life cycle (SDLC) baseline, and the local validation gates that ensure code quality and security before changes reach the main branch.

## CI/CD Pipeline Architecture

Palyra utilizes GitHub Actions for continuous integration, security auditing, and release orchestration. The pipeline is designed to be multi-platform, covering Linux, macOS, and Windows.

### Workflow Orchestration

The system is governed by several specialized workflows:

| Workflow              | File Path                                                                                         | Purpose                                                      |
| :-------------------- | :------------------------------------------------------------------------------------------------ | :----------------------------------------------------------- |
| **CI**                | [.github/workflows/ci.yml#1-1](http://.github/workflows/ci.yml#1-1)                               | Primary build/test suite for PRs and pushes to `main`.       |
| **Security Gates**    | [.github/workflows/security.yml#1-1](http://.github/workflows/security.yml#1-1)                   | Supply chain analysis, secret scanning, and SBOM generation. |
| **CodeQL**            | [.github/workflows/codeql.yml#1-1](http://.github/workflows/codeql.yml#1-1)                       | Semantic code analysis for Rust, Action, and JS/TS.          |
| **Release**           | [.github/workflows/release.yml#1-1](http://.github/workflows/release.yml#1-1)                     | Metadata preparation and multi-platform artifact bundling.   |
| **Dependency Review** | [.github/workflows/dependency-review.yml#1-1](http://.github/workflows/dependency-review.yml#1-1) | Vulnerability scanning for new dependencies in PRs.          |

### Data Flow: CI to Release

The following diagram illustrates the flow from code submission to release artifact generation.

**CI/CD Pipeline Flow**

```mermaid theme={null}
graph TD
    subgraph "PR/Push Trigger"
        A["git push"] --> B["ci.yml"]
        A --> C["security.yml"]
        A --> D["codeql.yml"]
    end

    subgraph "CI Job [ci.yml]"
        B --> B1["Build & Test (Matrix)"]
        B --> B2["Deterministic Core"]
        B --> B3["Workflow Regression"]
        B --> B4["Quality & Lints"]
    end

    subgraph "Security Job [security.yml]"
        C --> C1["cargo audit/deny"]
        C --> C2["Gitleaks"]
        C --> C3["OSV Scan"]
        C --> C4["SBOM Generation"]
    end

    subgraph "Release Job [release.yml]"
        E["Release Tag/Dispatch"] --> F["Prepare Metadata"]
        F --> G["Build Multi-OS Bundles"]
        G --> H["Upload Assets"]
        H --> I["Generate Attestations"]
    end

    B1 & B2 & B3 & B4 --> J["Status Check Pass"]
    C1 & C2 & C3 & C4 --> J
    J -->|Merge| E
```

**Sources:** [.github/workflows/ci.yml#16-215](http://.github/workflows/ci.yml#16-215), [.github/workflows/security.yml#11-156](http://.github/workflows/security.yml#11-156), [.github/workflows/release.yml#29-173](http://.github/workflows/release.yml#29-173)

***

## Security SDLC Baseline

Palyra enforces a "fail-closed" security baseline that scans the supply chain, detects high-risk patterns, and generates provenance data.

### 1. Supply Chain & Vulnerability Scanning

The `security-gates` job executes several industry-standard tools:

* **cargo-audit**: Checks `Cargo.lock` against the RustSec Advisory Database [.github/workflows/security.yml#95-96](http://.github/workflows/security.yml#95-96).
* **cargo-deny**: Enforces license compliance and bans problematic crates [.github/workflows/security.yml#98-99](http://.github/workflows/security.yml#98-99).
* **OSV Scanner**: Uses Google's Open Source Vulnerabilities database to find flaws in dependencies [.github/workflows/security.yml#101-104](http://.github/workflows/security.yml#101-104).
* **npm audit**: Validates the `apps/web` frontend dependencies, with a specific allowlist for dev-only advisories [.github/workflows/security.yml#30-63](http://.github/workflows/security.yml#30-63).

### 2. Static Analysis & Secret Detection

* **Gitleaks**: Scans the entire repository history for secrets, keys, and tokens [.github/workflows/security.yml#120-123](http://.github/workflows/security.yml#120-123).
* **CodeQL**: Performs deep semantic analysis. For Rust, it uses `build-mode: none` to keep CI lightweight while maintaining coverage [.github/workflows/codeql.yml#37-48](http://.github/workflows/codeql.yml#37-48).
* **High-Risk Pattern Scan**: A custom script (`check-high-risk-patterns.sh`) that flags dangerous code patterns or bypasses of the security model [.github/workflows/security.yml#128-129](http://.github/workflows/security.yml#128-129).

### 3. Artifact Hygiene and Provenance

* **Runtime Artifact Hygiene**: Ensures no temporary files, local databases, or build artifacts are accidentally committed [.github/workflows/security.yml#125-126](http://.github/workflows/security.yml#125-126).
* **SBOM Generation**: Produces a CycloneDX JSON Software Bill of Materials for every release [.github/workflows/security.yml#131-145](http://.github/workflows/security.yml#131-145).
* **Build Attestations**: Generates GitHub build attestations to provide verifiable provenance for release binaries [.github/workflows/release.yml#21-22](http://.github/workflows/release.yml#21-22).

**Sources:** [.github/workflows/security.yml#30-148](http://.github/workflows/security.yml#30-148), [.github/workflows/codeql.yml#37-48](http://.github/workflows/codeql.yml#37-48)

***

## Pre-Push Gate Scripts

To minimize CI failure cycles, developers use `scripts/run-pre-push-checks.sh`. This script mirrors the CI environment locally.

### Profiles

The gate supports two profiles via the `PALYRA_PRE_PUSH_PROFILE` environment variable [scripts/run-pre-push-checks.sh#5-5](http://scripts/run-pre-push-checks.sh#5-5):

1. **Fast (Default)**: Runs lints, `clippy`, and tests only for changed crates [scripts/run-pre-push-checks.sh#152-182](http://scripts/run-pre-push-checks.sh#152-182).
2. **Full**: Runs the entire workspace test suite and workflow regressions [scripts/run-pre-push-checks.sh#184-220](http://scripts/run-pre-push-checks.sh#184-220).

### Logic: Delta Testing

The script optimizes execution by detecting which Rust packages have changed relative to the upstream branch and only testing those [scripts/run-pre-push-checks.sh#96-112](http://scripts/run-pre-push-checks.sh#96-112). However, if global files like `Cargo.toml` or `rust-toolchain.toml` change, it forces a full workspace test [scripts/run-pre-push-checks.sh#114-126](http://scripts/run-pre-push-checks.sh#114-126).

**Pre-Push Logic Mapping**

```mermaid theme={null}
graph TD
    subgraph "Script: run-pre-push-checks.sh"
        START["Start"] --> DIR["resolve_cargo()"]
        DIR --> CLEAN["cleanup_runtime_artifacts()"]
        CLEAN --> PROFILE{Profile?}

        PROFILE -->|fast| FAST["run_fast_profile()"]
        PROFILE -->|full| FULL["run_full_profile()"]

        FAST --> JS["run_js_workspace_checks()"]
        JS --> LINT["cargo fmt & clippy"]
        LINT --> DELTA["run_changed_rust_package_tests()"]
        DELTA --> HYG["check_runtime_artifact_hygiene()"]
        HYG --> BUDGET["report-module-budgets.sh --strict"]
    end

    subgraph "Entity Mapping"
        DELTA -->|Calls| RPD["rust_package_dir_for_path()"]
        RPD -->|Reads| CT["Cargo.toml [name]"]
        BUDGET -->|Reads| AL["module-budget-allowlist.txt"]
    end
```

**Sources:** [scripts/run-pre-push-checks.sh#7-182](http://scripts/run-pre-push-checks.sh#7-182), [scripts/dev/report-module-budgets.sh#14-14](http://scripts/dev/report-module-budgets.sh#14-14)

***

## Architectural Boundary Ratchets

Palyra uses "ratchets" to prevent architectural erosion. These are enforced in CI via `quality` jobs.

### Module Budgets

The `report-module-budgets.sh` script enforces line-count limits on source files to prevent "God Objects."

* **Warn Threshold**: 1,200 lines [scripts/dev/report-module-budgets.sh#7-7](http://scripts/dev/report-module-budgets.sh#7-7).
* **Critical Threshold**: 3,000 lines [scripts/dev/report-module-budgets.sh#8-8](http://scripts/dev/report-module-budgets.sh#8-8).
* **Strict Mode**: In CI, it fails if any file exceeds 5,000 lines or if an entry point (`main.rs`/`lib.rs`) exceeds 2,500 lines [scripts/dev/report-module-budgets.sh#9-11](http://scripts/dev/report-module-budgets.sh#9-11).
* **Allowlist**: Files exceeding these limits must be explicitly added to `scripts/dev/module-budget-allowlist.txt` [scripts/dev/report-module-budgets.sh#14-14](http://scripts/dev/report-module-budgets.sh#14-14).

### Dependency Boundaries

The `check-architecture-boundaries.sh` script uses `git grep` to ensure crates do not import forbidden modules. Examples include:

* **Connectors**: Must stay provider-neutral and cannot import `palyra-daemon` or `palyra-policy` [scripts/check-architecture-boundaries.sh#57-61](http://scripts/check-architecture-boundaries.sh#57-61).
* **Vault**: Must remain runtime-independent (no `axum` or `tauri` imports) [scripts/check-architecture-boundaries.sh#69-74](http://scripts/check-architecture-boundaries.sh#69-74).
* **Frontend**: JS/TS code in `apps/web` cannot directly import Rust source files from `crates/` [scripts/check-architecture-boundaries.sh#75-79](http://scripts/check-architecture-boundaries.sh#75-79).

**Sources:** [scripts/dev/report-module-budgets.sh#7-19](http://scripts/dev/report-module-budgets.sh#7-19), [scripts/check-architecture-boundaries.sh#55-98](http://scripts/check-architecture-boundaries.sh#55-98)