Skip to content

feat(manta-cli,ci,docs): MAN-84 — guard release honesty and unblock the GitHub Release from GHCR failures ahead of cutting v0.1.0 - #126

Open
catalyst-cloud-connector[bot] wants to merge 1 commit into
mainfrom
MAN-84
Open

feat(manta-cli,ci,docs): MAN-84 — guard release honesty and unblock the GitHub Release from GHCR failures ahead of cutting v0.1.0#126
catalyst-cloud-connector[bot] wants to merge 1 commit into
mainfrom
MAN-84

Conversation

@catalyst-cloud-connector

@catalyst-cloud-connector catalyst-cloud-connector Bot commented Sep 7, 2026

Copy link
Copy Markdown

Why

manta's pitch is escaping a closed-source, build-from-source-only tool, but
at HEAD there are zero git tags and zero GitHub Releases — the README's
"download a prebuilt binary" story is false for every reader. MAN-21 built
the release pipeline already; this ticket is about making the first real tag
through it both safe to cut and honest about what it ships, per decision
D7 in docs/DECISIONS/2026-09-06-broad-review-decisions.md (tag now, don't
wait on the Pi4 CPU-budget gate).

This PR carries the repo-side changes only (plan Phases 1–3). It does not
cut the v0.1.0 tag itself
— that step needs push credentials to
HagaleTechnologies/manta that no agent container holds, and is documented
as a follow-up human/credentialed-agent action in the new runbook. Until
that tag is pushed, the ticket's Gherkin scenarios remain unmet; this PR is
what makes pushing it safe.

What changed

.github/workflows/release-publish.yml (+56/−3)

  • Added a verify-version job that fails the run if the pushed tag
    (vX.Y.Z) disagrees with [workspace.package] version in Cargo.toml,
    so a mistagged push can't publish binaries that answer a different
    version to --version. Deliberately not a needs: of build — a
    skipped job would skip its dependents, and build must still run on
    workflow_dispatch, where there's no tag to check.
  • Decoupled the release job from a failed docker-publish: it now gates
    on !cancelled() && needs.build.result == 'success' && needs.verify-version.result == 'success'
    instead of a plain needs: [build, docker-publish]. A first-ever GHCR
    package push is the leg most likely to fail, and per the ticket ("don't
    block this ticket on GHCR being public — the GitHub Release binaries are
    the priority"), that failure must not take the Release down with it.
    docker-publish itself also gained needs: [verify-version, build] with
    its own gate, so a version-mismatched tag can't still push a mistagged
    GHCR image even though the Release is correctly suppressed.
  • Added a body: to the release-notes step, a short pre-stability banner
    that prepends to GitHub's generate_release_notes: true changelog rather
    than replacing it.

README.md (+4/−1) — ## Status now opens with "Pre-stability
alpha, expect breakage."
instead of a bare "Pre-1.0.", stating that
v0.1.0 hasn't cleared M2/M3 acceptance and that CLI flags, config keys,
and the JSON spot schema can still change without a deprecation path. This
also lands inside every release archive, since the packaging step copies
README.md into each one.

crates/manta-cli/tests/release_copy.rs (new) — three repo-property
tests, run by this repo's required test (ubuntu-latest) / test (macos-latest) checks on every PR forever:

  • README and release-notes body: both contain the pre-stability phrase
    (case-insensitively, since prose capitalizes it mid-sentence).
  • The release job's own if: line (extracted via a small job-block
    parser, not a whole-file grep, so a match in a neighboring job can't
    satisfy it) requires needs.build.result == 'success' and must not
    reference docker-publish.
  • The verify-version job still contains its real
    "$TAG_VERSION" != "$CARGO_VERSION" comparison, not just its name.

docs/RUNBOOKS/release.md (new, 174 lines) — the previously
undocumented procedure for cutting a release: preconditions, the exact
git tag -a/git push invocation, watching the workflow run, verifying
the published release as an operator would (download → unpack → run →
decode), the one-time GHCR visibility flip (explicitly non-blocking, per
MAN-65/MAN-66), and how to unwind a bad release. MAN-65's planned Phase 4/5
should extend this file rather than create a second one.

Verification

All from the validation report (d292166 vs. base e398d46):

  • cargo test -p manta-cli --test release_copy — 3 passed (observed red
    before the README/workflow copy landed, green after).
  • cargo test --workspace — 469 passed, 0 failed, 0 ignored, 40 targets;
    no regression.
  • cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --all --check — clean.
  • All three workflow YAML files parse; job graph is
    ["verify-version", "build", "docker-publish", "release"] as intended.
  • verify-version's shell logic executed directly against the real
    Cargo.toml: exit 0 for v0.1.0, exit 1 for v0.2.0 and for
    v0.1.0+linux (the latter incidentally also covers MAN-65 finding 1's
    build-metadata-tag case, though not by design).
  • A packaged release archive was built and run outside the checkout:
    ./manta --versionmanta 0.1.0; ./manta gen v1 && ./manta decode
    → correct W1AW decode, spots: 1.
  • code-review at high effort found six issues, all test-coverage /
    robustness / maintainability / documentation, none correctness or
    security — for example, the GHCR-decoupling guard doesn't itself assert
    !cancelled() (the line that actually does the decoupling), and the
    release-notes guard greps the whole workflow file rather than scoping to
    the release job's body:. Per this repo's review-convergence
    policy
    , these
    are follow-up-ticket material rather than blocking, since they're
    hardening the guards this same PR introduces rather than fixing shipped
    behavior.
  • Not run in any container so far: the four non-native build-matrix legs
    (macOS x86_64/arm64, Windows MSVC, Linux arm64 via cross) and the
    multi-arch docker buildx/GHCR push — this PR's own release.yml
    pull_request trigger path-matches release-publish.yml, so opening it
    exercises all five matrix legs and the Docker build as the only pre-tag
    signal on them.

Not in scope

  • Cutting the v0.1.0 tag itself (Phase 4) — requires push credentials no
    agent container holds; procedure is docs/RUNBOOKS/release.md.
  • MAN-65's remaining hardening (OCI-grammar tag validation,
    scripts/release-version.sh, GHCR-public-by-default) — none of its four
    findings block this specific tag; tracked separately.
  • Making the GHCR package public (MAN-65 finding 4 / MAN-66) — explicitly
    not a blocker for the GitHub Release deliverable.
  • SHA256SUMS, CLI --help jargon cleanup, Windows CRT linkage — out of
    this ticket's Gherkin.

edd86eb feat: MAN-84 — Operators should be able to download a v0.1.0 release instead of building manta from source
6618f2a feat: MAN-84 — Operators should be able to download a v0.1.0 release instead of building manta from source
d292166 feat: MAN-84 — Operators should be able to download a v0.1.0 release instead of building manta from source

Catalyst-Replay-Squash: e398d46
@catalyst-cloud-connector catalyst-cloud-connector Bot changed the title feat: MAN-84 — Operators should be able to download a v0.1.0 release instead of building manta from source feat(manta-cli,ci,docs): MAN-84 — guard release honesty and unblock the GitHub Release from GHCR failures ahead of cutting v0.1.0 Sep 7, 2026
@catalyst-cloud-connector
catalyst-cloud-connector Bot marked this pull request as ready for review September 7, 2026 05:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants