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).

Currency note (2026-09-26). Sections 1 to 5 and 8 describe the Sprint 43 multi-platform pipeline design. The shipped publication path today is the stella-cli image, published by digest through the manually dispatched .gitea/workflows/stella-cli-publish.yml lane; see docs/runbooks/deploy/v1-publication-dispatch.md. Section 2 step 9, section 5.2 and section 6 were corrected against src/ on this date.

1 · Release Artifacts

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 (StellaOps.Cli.Tests, including CliDocumentationContractTests); the Task Pack verb group was deleted 2026-09-14 (SPRINT_20260914_003 JEF-4), so there are no pack commands to exercise.
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. Documentation parity – CliDocumentationContractTests (step 4) is the enforced command-truth gate; see section 6. No automated CLI-versus-Console parity gate runs.

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 and the registry mirror. (A pack bundle export verb never existed and the stella pack … group was deleted 2026-09-14, JEF-4; pack content for offline seeds is exported by the registry’s POST /api/v1/export/offline-seed, see docs/security/pack-signing-and-rbac.md §7.1.)

No stella subcommand packages the CLI itself. Carry the published stella-cli image into the sealed site by digest (for example docker save on the connected side and docker load on the sealed side), or copy the platform archives with their checksums and signatures.

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

6 · Parity Gating

• Documentation examples. CliDocumentationContractTests in StellaOps.Cli.Tests parses every runnable-looking stella example in docs/ against the real command tree. An example that does not parse fails the test unless it is listed in unshipped-command-examples.json, and a listed entry that starts parsing or disappears fails it too (policy).
• CLI versus Console. The capability matrix in cli-vs-ui-parity.mdis maintained by hand. No stella subcommand and no CI lane checks it; review it for each release.
• 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).