CI recipes architecture

This page describes how the Stella Ops CI recipe catalogue is structured and the determinism contract every recipe must honour. It is for engineers authoring or reviewing the pipeline templates under ci-recipes.md. Stella Ops is an offline-first DevOps vulnerability scanner and release control plane, so every recipe is expected to run identically — and reproducibly — on connected and air-gapped runners alike.

Scope & responsibilities

• Curate deterministic CI pipeline templates for ingestion, scanning, policy evaluation, export, and notifications.
• Capture provenance for each recipe (inputs, pinned tool versions, checksum manifests) and keep offline/air-gap parity.
• Provide reusable fragments (YAML/JSON) plus guardrails (AOC checks, DSSE attestation hooks, Rekor/transparency toggles).

Components

• Recipe catalogue (ci-recipes.md) — Source of truth for pipeline snippets; sorted deterministically and annotated with required secrets/scopes.
• Guardrail hooks — Inline steps for schema validation, SBOM/VEX signing, and attestation verification; reuse Authority/Signer/Export Center helpers.
• Observability shim — Optional steps to emit structured logs/metrics to Telemetry Core when allowed; defaults to no-op in sealed/offline mode.
• Offline bundle path — Scripts/guides to package recipes and pinned tool archives for air-gapped runners; hashes recorded in release notes.

Data & determinism

• All generated artifacts (templates, manifests, example outputs) must sort keys and lists, emit UTC ISO-8601 timestamps, and avoid host-specific paths.
• DSSE/attestation helpers should target the platform trust roots defined in Authority/Sigstore docs; prefer BLAKE3 hashing where compatible.
• Keep retry/backoff logic deterministic for reproducible CI runs; avoid time-based jitter unless explicitly documented.

Integration points

• Authority/Signer for DSSE + Rekor publication; Export Center for bundle assembly; Notify for preview hooks; Telemetry Core for optional metrics.
• Recipes must remain compatible with the CLI/SDK surface referenced in docs/modules/cli/guides/ and DevPortal snippets.
• For the build-time attestation primitives a recipe wraps, see DSSE build flow.

Testing lanes and catalog

• CI lane filters are defined by docs/technical/testing/TEST_CATALOG.yml and aligned with docs/technical/testing/testing-strategy-models.md.
• Standard categories: Unit, Contract, Integration, Security, Performance, Live (opt-in only).
• Any new test gate or lane must update docs/technical/testing/TEST_SUITE_OVERVIEW.md and docs/technical/testing/ci-quality-gates.md.

Change process

• Track active work in the relevant sprint file under docs/implplan/SPRINT_*.md.
• When adding new recipes, include offline notes, determinism checks, and minimal test-harness references in docs/benchmarks/ or the owning test project under src/** as applicable.