git.stella-ops.org/ops/deployment/cli

StellaOps CLI Release Packaging

Scope

• Package and publish StellaOps CLI binaries for all supported OS/arch targets with checksums, signatures, completions, and a container image.
• Outputs feed three lanes: (1) public release mirrors, (2) air-gapped/offline kit, (3) internal regression runners.
• Source artefacts come from DevOps pipelines (.gitea/workflows/cli-build.yml, .gitea/workflows/cli-chaos-parity.yml).

Inputs (expected layout)

out/cli/<version>/
  stella-cli-linux-amd64.tar.gz
  stella-cli-linux-arm64.tar.gz
  stella-cli-darwin-arm64.tar.gz
  stella-cli-windows-amd64.zip
  completions/
    bash/stella
    zsh/_stella
    fish/stella.fish
  parity/
    parity-report.json
  sbom/
    stella-cli.spdx.json

<version> must match the git tag and container tag (e.g., 2025.12.0).

Packaging steps (deterministic)

1. Set version and workdir

export CLI_VERSION=2025.12.0
export CLI_OUT=out/cli/$CLI_VERSION

2. Generate checksums (sorted, LF endings)

cd "$CLI_OUT"
find . -maxdepth 1 -type f \( -name 'stella-cli-*' -o -name '*.zip' \) \
  -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS

3. Sign checksum file (cosign keyless or key)

COSIGN_YES=true cosign sign-blob \
  --key env://MIRROR_SIGN_KEY_B64 \
  --output-signature SHA256SUMS.sig \
  --output-certificate SHA256SUMS.pem \
  SHA256SUMS

4. Build/push container image (optional if pipeline already produced)

docker build -t registry.local/stella/cli:$CLI_VERSION -f deploy/compose/cli/Dockerfile .
docker push registry.local/stella/cli:$CLI_VERSION

5. Produce offline image tar (for airgap kit)

docker pull registry.local/stella/cli:$CLI_VERSION
docker save registry.local/stella/cli:$CLI_VERSION \
  | gzip -9 > stella-cli-image-$CLI_VERSION.tar.gz

6. Bundle completions

tar -C "$CLI_OUT/completions" -czf stella-cli-completions-$CLI_VERSION.tar.gz .

7. Publish artefact manifest (for mirrors/offline kit)

cat > release-manifest-$CLI_VERSION.json <<'EOF'
{
  "version": "REPLACE_VERSION",
  "binaries": [
    "stella-cli-linux-amd64.tar.gz",
    "stella-cli-linux-arm64.tar.gz",
    "stella-cli-darwin-arm64.tar.gz",
    "stella-cli-windows-amd64.zip"
  ],
  "completions": "stella-cli-completions-REPLACE_VERSION.tar.gz",
  "checksums": "SHA256SUMS",
  "signatures": ["SHA256SUMS.sig", "SHA256SUMS.pem"],
  "container": {
    "image": "registry.local/stella/cli:REPLACE_VERSION",
    "offline_tar": "stella-cli-image-REPLACE_VERSION.tar.gz"
  }
}
EOF
sed -i "s/REPLACE_VERSION/$CLI_VERSION/g" release-manifest-$CLI_VERSION.json

Distribution lanes

• Mirror / public: upload binaries, completions, SBOM, SHA256SUMS*, and release-manifest-<version>.json to the mirror bucket; expose via CDN.
• Offline kit: copy the same files plus stella-cli-image-<version>.tar.gz into out/offline-kit/cli/ before running ops/offline-kit/scripts/build_offline_kit.sh.
• Internal runners: sync SHA256SUMS and SHA256SUMS.sig to the runner cache; store container tar in the runner image cache path.

Verification

cd "$CLI_OUT"
sha256sum --check SHA256SUMS
cosign verify-blob --key env://MIRROR_SIGN_KEY_B64 --signature SHA256SUMS.sig --certificate SHA256SUMS.pem SHA256SUMS

Rollback / re-spin

• To revoke a bad drop, delete the mirror path for that version and reissue release-manifest-<version>.json with "revoked": true field; keep signatures for audit.
• Re-spin by rerunning steps with a new version tag; never overwrite artefacts in-place.

Evidence to attach in sprint

• SHA256SUMS, SHA256SUMS.sig, release-manifest-<version>.json, and offline image tar path uploaded to sprint evidence locker.