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.