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

Audience: Release engineers and DevOps operators who build, sign, and ship the stella CLI. Scope: Release artifacts, the build pipeline, versioning and channels, signing and verification, online and air-gapped distribution, parity gating, and the release checklist.

This runbook describes how to build, sign, package, and distribute the Stella Ops CLI with Task Pack support. It covers connected and air-gapped workflows, SBOM generation, parity gating, and the 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

Source checkout – pinned commit, reproducible environment (Docker).
Dependency lock – dotnet restore, npm ci (for CLI frontends), ensure deterministic build flags.
Build binaries – cross-platform targets with reproducible timestamps.
Run tests – unit + integration; include stella pack commands (plan/run/verify) in CI.
Generate SBOM – syft packages dist/stella-linux-x64 --output cyclonedx-json.
Bundle – compress artifacts, include completions (bash, zsh, fish, PowerShell).
Sign – cosign signatures for binaries, checksums, container image.
Publish – upload to downloads.stella-ops.org, container registry, Packs Registry (for CLI container).
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/modules/cli/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/modules/cli/guides/overview.md, pack authoring guide, release notes.
Document new flags/commands in the pack authoring guide (docs/modules/cli/guides/packs-profiles.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).