mirror of https://github.com/ruvnet/RuView synced 2026-07-20 17:03:24 +00:00

Files

T

ruv be4efecbcd cog-ha-matter (ADR-116 P8): app-registry entry stub + release checklist

Two closing P8 deliverables that complete the local-side publishing
scaffolding. The remaining work is all credential-bearing user
action.

1. `cog/app-registry-entry.json` — the exact JSON payload to paste
   into cognitum-one's `app-registry.json`. Schema discovered by
   fetching the live registry (105 cogs, 11 categories) and
   matching the existing `ruview-densepose` entry verbatim. Keys:

     id, name, category, version, size_kb, difficulty, description,
     featured, config[], sha256, binary_size

   cog-ha-matter slots in under `category: "building"` (smart home
   / building automation — the natural HA / Matter category, vs
   `network` which is more about transport bridges).

   7 config[] entries mirror our CLI surface:
     sensing_url, mqtt_host, mqtt_port, privacy_mode,
     mdns_hostname, mdns_ipv4, no_mdns

   Two post-build fields left as `<FILL_IN_...>` markers:
     sha256       (paste from the workflow artifact's .sha256)
     binary_size  (wc -c < the binary)

   Schema validated: all 10 required keys present, parses as JSON.

2. `cog/RELEASE-CHECKLIST.md` — one-page mechanical playbook with
   four explicit "🔑 USER ACTION" gates. Each gate names exactly
   what the user (or org admin) has to do that the pipeline cannot:

     a) provision GCP_CREDENTIALS + HAS_GCP_CREDENTIALS org var
     b) provision COGNITUM_OWNER_SIGNING_KEY GH secret
     c) gcloud auth login (only if uploading locally)
     d) PR app-registry.json into cognitum-one

   Plus pre-release test gate, tag-push command, post-release
   verification curl, and a rollback procedure using GCS object
   versioning (per ADR-100 §"GCS misconfiguration risks").

Stop-condition check (cron's predicate: "ALL local-side publishing
scaffolding is complete and the only remaining work requires user
action"):

  ✅ cog/manifest.template.json
  ✅ cog/Makefile (build / sign / upload / verify / clean)
  ✅ cog/README.md
  ✅ cog/app-registry-entry.json (this commit)
  ✅ cog/RELEASE-CHECKLIST.md (this commit)
  ✅ .github/workflows/cog-ha-matter-release.yml (3 jobs, gated)
  ✅ dist/ handling (gitignored, created by make)

  🔑 4 user-action gates explicitly enumerated in the checklist

The cron should STOP after this iter — the local-side scaffolding
is complete and the remaining work is the four named credential
gates that the pipeline cannot self-serve.

Co-Authored-By: claude-flow <ruv@ruv.net>

2026-05-23 23:12:14 -04:00

3.2 KiB

Raw Blame History

cog-ha-matter Release Checklist

Mechanical steps to publish a new version. Everything local-side is automated; the four "🔑 USER ACTION" blocks below are the only manual gates. Each one is a credential-bearing step the cog/ pipeline cannot do on its own.

1. Pre-release (local)

# Bump version in v2/crates/cog-ha-matter/Cargo.toml then:
cargo test -p cog-ha-matter --no-default-features --lib   # 64+ tests must pass
cargo check -p cog-ha-matter --no-default-features        # green

2. Tag the release

git tag cog-ha-matter-v$(cargo pkgid -p cog-ha-matter | sed -E 's/.*#//')
git push origin --tags

The push fires .github/workflows/cog-ha-matter-release.yml which:

builds cog-ha-matter-x86_64 + cog-ha-matter-arm (cross-compiled via apt-installed gcc-aarch64-linux-gnu)
computes SHA-256 sidecars
runs the Ed25519 sign step if COGNITUM_OWNER_SIGNING_KEY is set
uploads workflow artifacts (always — these are downloadable from the run page)
uploads to gs://cognitum-apps/cogs/{arch}/ if the org var HAS_GCP_CREDENTIALS == 'true' and the GCP_CREDENTIALS secret is set

3. Update app-registry.json

Take cog/app-registry-entry.json from this directory, fill in the post-build values, and PR it into the cognitum-one repo at app-registry.json.

Values to fill in:

version — bump to match the new tag
sha256 — paste from the workflow artifact's .sha256 sidecar
binary_size — bytes of the binary (wc -c < cog-ha-matter-x86_64)

🔑 USER ACTION items (cannot be automated)

#	What	Why this can't be automated
1	Set the `HAS_GCP_CREDENTIALS` org variable to `true` and provision the `GCP_CREDENTIALS` GitHub Actions secret with a service-account JSON that has `storage.objectAdmin` on `gs://cognitum-apps/cogs/`	Requires org-admin access + a GCP project owner's signoff
2	Provision `COGNITUM_OWNER_SIGNING_KEY` GitHub secret with the Ed25519 private key in PEM form	Long-lived secret material; humans must rotate it; same blocker for cog-pose-estimation
3	`gcloud auth login` (only if running `make upload` locally instead of via CI)	Browser OAuth flow
4	File a PR in `cognitum-one` against `app-registry.json` adding the entry from `cog/app-registry-entry.json`	Cross-repo write requires the user's GitHub auth + reviewer signoff

Post-release verification

Once the cognitum-one PR merges and the cache rolls over (~hourly):

curl -sS https://storage.googleapis.com/cognitum-apps/app-registry.json \
  | jq '.[] | select(.id == "ha-matter")'

Should print the new entry. On the Seed UI, the cog appears under Settings → Cogs → building → Home Assistant + Matter Bridge.

Reverting a bad release

Cogs ship via GCS object versioning (per ADR-100). To roll back:

gsutil ls -a gs://cognitum-apps/cogs/x86_64/cog-ha-matter-x86_64
# Pick the previous generation, then:
gsutil cp gs://cognitum-apps/cogs/x86_64/cog-ha-matter-x86_64#<generation> \
          gs://cognitum-apps/cogs/x86_64/cog-ha-matter-x86_64

Then PR a version bump in cognitum-one's app-registry.json so Seeds know to refetch.

3.2 KiB Raw Blame History