CI/CD documentation — agent guide

Purpose & audience

This is the working charter for agents (and humans) editing the Stella Ops CI/CD documentation set under docs/technical/cicd/. Stella Ops is a self-hosted, offline-first DevOps vulnerability scanner and release control plane; its CI pipelines must stay deterministic, reproducible, and air-gap friendly. This guide explains where the CI docs live, what to read first, and the guardrails that keep the pages trustworthy.

Key docs in this set

• CI/CD overview — entry point: trigger tiers, workflow categories, promotion flow.
• CI architecture — scope, components, and determinism contract for the recipe catalogue.
• CI recipes — cut-and-paste pipeline snippets (Jenkins, CircleCI, Gitea Actions, Docs CI).
• Workflow triggers — trigger reference and dependency graph.
• Path filters — which workflows run for which changed files.
• Release pipelines — suite/module/bundle/service releases, rollback, promotion.
• DSSE build flow — build-time in-toto/DSSE attestation walkthrough.
• SARIF integration and scoring configuration — Smart-Diff CI surfaces.

Required reading

• Platform architecture overview.
• Aggregation-Only Contract — honour it wherever recipes touch ingestion.

How to get started

1. Find the relevant story in the active sprint files under docs/implplan/SPRINT_*.md.
2. Read the CI architecture and overview for domain context before editing.
3. Verify any technical claim (workflow name, job, registry, scope) against the source of truth — the workflow YAML under .gitea/workflows/ (and .gitea/workflows-archived/) and the code under src/ — before relying on it.
4. Coordinate cross-module changes through the sprint plan and the repo-wide /AGENTS.md.

Guardrails

• Code wins. When a doc and the workflow/source disagree, fix the doc. Do not invent endpoints, scopes, registry names, or job names you cannot verify.
• Preserve determinism. Sort outputs, normalise timestamps to UTC ISO-8601, and avoid machine-specific artefacts in any example a reader will copy.
• Keep Offline Kit parity in mind. Document the air-gapped path for any new recipe or workflow.
• Update runbooks and observability assets when operational characteristics change.
• Track status in the owning sprint file (TODO → DOING → DONE/BLOCKED); revert to TODO if you pause without shipping.