git.stella-ops.org/docs/operations/cli-release-and-packaging.md

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.

CLI Release & Packaging Runbook

This runbook describes how to build, sign, package, and distribute the StellaOps CLI with Task Pack support. It covers connected and air-gapped workflows, SBOM generation, parity gating, and distribution artifacts required by Sprint 43 (DEVOPS-CLI-43-001, DEPLOY-PACKS-43-001).

---

1 · Release Artifacts

Artifact	Description	Notes
stella-<version>-linux-x64.tar.gz	Linux binary + completions	Includes man pages, localization files.
stella-<version>-macos-universal.tar.gz	macOS universal binary	Signed/notarized where applicable.
stella-<version>-windows-x64.zip	Windows binary + PowerShell modules	Code-signed.
stella-cli-container:<version>	OCI image with CLI + pack runtime	Deterministic rootfs (scratch/distroless).
SBOM (.cdx.json)	CycloneDX SBOM per artifact	Generated via stella sbom generate or syft.
Checksums (SHA256SUMS)	Aggregated digest list	Signed with cosign.
Provenance (.intoto.jsonl)	DSSE attestation (SLSA L2)	Contains build metadata.
Release notes	Markdown summary	Links to task packs docs, parity matrix.

---

2 · Build Pipeline

1. Source checkout – pinned commit, reproducible environment (Docker).
2. Dependency lock – dotnet restore, npm ci (for CLI frontends), ensure deterministic build flags.
3. Build binaries – cross-platform targets with reproducible timestamps.
4. Run tests – unit + integration; include stella pack commands (plan/run/verify) in CI.
5. Generate SBOM – syft packages dist/stella-linux-x64 --output cyclonedx-json.
6. Bundle – compress artifacts, include completions (bash, zsh, fish, PowerShell).
7. Sign – cosign signatures for binaries, checksums, container image.
8. Publish – upload to downloads.stella-ops.org, container registry, Packs Registry (for CLI container).
9. Parity gating – run CLI parity matrix tests vs Console features (automation in DEVOPS-CLI-43-001).

CI must run in isolated environment (no network beyond allowlist). Cache dependencies for offline bundling.

---

3 · Versioning & Channels

• Semantic versioning (YYYY.MM.patch), e.g., 2025.10.0.
• Channels:
  • edge – nightly builds, limited support.
  • beta – pre-release candidates.
  • stable – production-ready, after parity gating.
• Release promotions mirror Task Pack channels; update downloads manifest (deploy/downloads/manifest.json).

---

4 · Signing & Verification

• Binaries signed with cosign (cosign sign-blob).
• Container image signed (cosign sign stella-cli-container:<version>).
• DSSE provenance includes:
  • Build pipeline ID.
  • Source commit and repo.
  • Dependencies SBOM digest.
  • Test results summary.
• Verification command for operators:

cosign verify-blob \
  --certificate-identity https://ci.stella-ops.org \
  --certificate-oidc-issuer https://fulcio.sigstore.dev \
  --signature stella-2025.10.0-linux-x64.sig \
  stella-2025.10.0-linux-x64.tar.gz

---

5 · Distribution

5.1 Online

• Publish artifacts to Downloads service; update manifest with digests, SBOM URLs, attestations.
• Update CLI parity docs (docs/cli-vs-ui-parity.md) and release notes.
• Push container image to registry with SBOM + attestations referenced as OCI referrers.
• Notify stakeholders via #release-cli channel and release mailing list.

5.2 Offline / Air-Gap

• Bundle CLI artifacts, Task Pack samples, and registry mirror:

stella pack bundle export \
  --packs "sbom-remediation:1.3.0" \
  --output offline/packs-bundle-2025.10.0.tgz

stella cli bundle export \
  --output offline/cli-2025.10.0.tgz \
  --include-container \
  --include-sbom

• Update Offline Kit manifest with new CLI version and pack bundle entries.
• Provide import scripts (ouk import) for sealed sites.

---

6 · Parity Gating

• stella cli parity check compares CLI commands vs parity matrix.
• CI fails release if any required command flagged 🟥 or 🟡 with severity > threshold.
• Parity report uploaded to Downloads workspace and linked in docs.
• Manual review required for new commands (ensure man pages and help text localized).

---

7 · Localization & Documentation

• CLI includes localization bundles; ensure i18n.txz packaged.
• Update man pages (man/stella-pack.1) and HTML docs.
• Sync docs: docs/cli/overview.md, pack authoring guide, release notes.
• Document new flags/commands in docs/cli/commands/pack.md (tracked in Sprint 42 tasks).

---

8 · Release Checklist

• All binaries built reproducibly (CI logs archived).
• Tests + parity matrix passing.
• SBOM + provenance generated and published.
• Cosign signatures created and verified.
• Downloads manifest updated (edge/beta/stable).
• Offline bundle exported and validated.
• Release notes + documentation updates merged.
• Notifications sent (chat/email).
• Imposed rule reminder present at top of document.

---

Last updated: 2025-10-27 (Sprint 43).