135 lines
5.3 KiB
Markdown
135 lines
5.3 KiB
Markdown
> **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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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).*
|
||
|