Release Maple

Release Maple

Treat every release step as a production action. Do not use this workflow for routine validation. Before a write, state the exact repository, version, tag, commit, external effect, and authority provided by the user.

Know the triggers

• A push to master starts production-shaped desktop, Android, iOS, web, frontend, and Rust workflows. The iOS master workflow uploads its verified IPA to TestFlight automatically.
• Mobile App CI serializes production iOS build/export, verification, and upload so concurrent master pushes cannot reuse an export-assigned build number. Its master-only manual dispatch forces a fresh build even without app changes. After a duplicate-build rejection, dispatch this full workflow from master; retrying only submission reuses the rejected IPA's build number.
• The independent Maple Dev TestFlight workflow also builds every master push and uploads the distinct cloud.opensecret.maple.dev application for internal testing against the existing development services. Manual dispatch accepts master only. Its app identity, credentials, artifact verification, internal group setup, and retry contract are documented in Maple Dev on TestFlight.
• Creating a GitHub Release starts the cross-platform release workflow. A successful release workflow starts separate updater-metadata, Pages, and best-effort Zapstore workflows. These siblings never gate or change the core Maple release. Pages has staged modes: Promote Pages production advances the branch for native Cloudflare builds by default; when repository variable MAPLE_PAGES_PRODUCTION_ENABLED=true, Publish Pages uploads the verified existing release web artifact instead. Read the Pages publisher architecture for its source contract. Mode activation, environment administration, and Cloudflare build controls belong to a separately authorized operator procedure.
• The same Maple GitHub Release receives four native maple-proxy archives and their checksum manifest. Never create a separate proxy Release or proxy tag; /releases/latest must continue to identify the Maple application release.
• Maple GitHub Releases do not publish maple-sdk or maple-proxy to crates.io. A successful stable release starts a non-gating GHCR sibling that builds only for a new or missing non-baseline proxy version. It treats exact version tags as immutable, verifies release provenance and container inputs, and repairs minor, major, and latest aliases without rebuilding an existing exact image. Version 0.3.3 is the explicit unbackfilled migration baseline. The container remains separately versioned at ghcr.io/mapleprivacylabs/maple-proxy.
• GitHub Release creation does not itself submit the release IPA or AAB to Apple App Store review or Google Play.

Never push or merge master, create a release, retry a workflow, upload to a store, submit for review, or alter a rollout merely to see whether it works.

Repository-transfer checkpoint

Before creating a new release, verify that repo.meta.json identifies MaplePrivacyLabs/Maple as the canonical repository. Keep the existing updater Worker serving its deployed metadata until the first normal new-org release. Do not manually republish retained v3.3.10 updater metadata: its asset URLs use OpenSecretCloud/Maple, while the publisher and new Worker correctly require the current canonical owner. The next release generates new-owner URLs without changing the legacy updater fallback compiled into existing clients.

The first eligible proxy container publication initializes ghcr.io/mapleprivacylabs/maple-proxy with a manual Publish proxy container run from master and bootstrap_only=true. This validates the current release and uploads only content-addressed images, without version or alias tags. It does not treat failed package enumeration as an empty inventory. GitHub creates new packages privately; make that package public in its settings, retain Maple Actions write access, then rerun only the proxy publisher with both manual inputs disabled. For read-only API diagnosis, use diagnostics_only=true; its success reports completed observations, not publication readiness. Do not create another release, change proxy versions, or overwrite exact tags to repair package visibility. Existing old-namespace images receive no updates.

Prepare the version

1. Prepare the bump on a clean focused branch based on current origin/master; do not switch another worktree to master or force its owning worktree off that branch. Compare the checked-in version with the latest release:

   git fetch origin master
   git merge-base --is-ancestor origin/master HEAD
   current_version="$(nix develop --no-update-lock-file .#ci -c just get-version | tail -n 1)"
   released_version="$(gh api repos/MaplePrivacyLabs/Maple/releases/latest --jq '.tag_name | ltrimstr("v")')"
   printf 'current=%s released=%s\n' "$current_version" "$released_version"

2. If current_version is newer, retain that pending version unless the user explicitly chooses a different target. For example, a requested 3.4.0 replaces a pending 3.3.11; a generic request to release does not trigger another bump. The chosen target must still be newer than the published release.

3. If versions are equal, establish the intended next version. Proceed when the user names an exact version or patch/minor/major level. If the user delegates the choice, use patch; do not infer minor or major from commits.

4. On a focused branch, run exactly one repository helper:

   nix develop --no-update-lock-file .#ci -c just update-version X.Y.Z
   nix develop --no-update-lock-file .#ci -c just bump-patch
   nix develop --no-update-lock-file .#ci -c just bump-minor
   nix develop --no-update-lock-file .#ci -c just bump-major

5. Review all manifest, Apple project, Android version-code, and apps/maple-research/frontend/src-tauri/Cargo.lock changes. Run the applicable Maple validation gates and submit the isolated bump through normal review when authorized. Do not use just release; it creates a local tag before the reviewed GitHub flow.

6. After the bump merges, use or create a clean worktree on master. If another worktree already owns that branch, use its checkout instead of forcing or stealing it. Pull with --ff-only and wait for the required CI evidence. Release only current master; preflight verifies it again.

Run preflight

Run the bundled fail-closed preflight from the repository root:

preflight="$(.agents/skills/release-maple/scripts/preflight.sh)"
printf '%s\n' "$preflight" | jq .
tag="$(printf '%s' "$preflight" | jq -r .tag)"
previous_tag="$(printf '%s' "$preflight" | jq -r .previous_tag)"
head_sha="$(printf '%s' "$preflight" | jq -r .head_sha)"

The script requires a clean current master, exact manifest version parity, a newer version and unused tag, and successful executed master-push CI jobs. CodeQL must run on the exact release commit. Research test/build evidence may come from an ancestor only when the complete Git tree diff contains exclusively independent Agent, documentation, agent guidance, or release-gate test-harness changes. Unknown paths and changes to Research, SDK, proxy, shared scripts, workflows, or Nix require fresh evidence. Skipped builds never count as build proof; the helper searches a bounded workflow history and rejects newer failures, pending runs, missing jobs, changed inputs, and non-ancestors. The returned ci_evidence records each actual run, tested SHA, and whether it was reused. Preflight also rechecks master after collecting evidence. Stop on any failure; correct it through the normal reviewed process. Never overwrite or move a release tag.

Review the SDK consumer version policy for the clients being released. Record the frontend's selected SDK from its manifest/lockfile and each Rust consumer's resolved version/source using the policy's cargo metadata --locked command. Local links are allowed. If those clients will ship unpublished SDK changes, recommend publishing the SDK and pinning those consumers first; an intentional local-source release can proceed with the exact monorepo commit recorded. Unrelated SDK source changes do not require a pinned client to upgrade, and this preference adds no release gate.

When preparing an enclave trust or PCR rotation change, review both browser consumers' embedded fallbacks against the approved development and production histories: apps/maple-research/frontend/src/config/openSecretClientConfig.ts and apps/maple-auth/src/config/openSecretClientConfig.ts. Verify each affected app's combined app-provided and pinned-SDK roots support its intended approved enclave measurements when signed-history fetching is unavailable, preserving development/production separation. Record affected artifacts and any pending rollout in the handoff. Auth owns a separate SDK pin and publisher: refreshing Research does not update Auth, and an Auth publication remains a separately authorized operation under the Pages guide. This is a compatibility review of each consumer, not a requirement to keep their lists byte-identical or release them together.

Record the proxy version and inspect its own runtime inputs since previous_tag:

proxy_version="$(sed -n 's/^version = "\([^"]*\)"/\1/p' proxy/Cargo.toml | head -n 1)"
git diff --name-only "$previous_tag".."$head_sha" -- proxy
printf 'proxy_version=%s\n' "$proxy_version"

Inspect the proxy's manifest and lockfile at both revisions. Include changes under sdk/rust in its runtime comparison when either revision uses that local SDK. With registry dependencies at both revisions, compare the selected SDK versions/checksums in proxy/Cargo.lock; unrelated sdk/rust edits are not proxy runtime changes. The embedding app's SDK selection is separate from the standalone proxy's lockfile.

If consumed runtime inputs changed without a proxy version change, stop and make the version decision explicit before publishing. A normal Maple Release always builds the checked-in proxy version, but that does not implicitly authorize a crates.io or GHCR publish.

Preview GitHub's generated notes:

gh api --method POST repos/MaplePrivacyLabs/Maple/releases/generate-notes \
  -f tag_name="$tag" \
  -f target_commitish="$head_sha" \
  -f previous_tag_name="$previous_tag" | jq -r '.name, .body'

Confirm the notes span the intended changes and recheck that head_sha is still origin/master. GitHub's generated body is changelog input, not a complete public release description. Draft a concise user-facing summary and highlights from the exact release diff, place them above the generated notes, and review the complete Markdown in a temporary notes_file. Do not publish a PR-list-only description when the release has meaningful product changes. Present the tag, commit, previous tag, and final notes to the user before creating the release unless the current request already gives unambiguous authority for that exact release.

Publish once

Create the GitHub Release exactly once. This creates the tag in the same flow:

gh release create "$tag" \
  --repo MaplePrivacyLabs/Maple \
  --target "$head_sha" \
  --title "$tag" \
  --notes-file "$notes_file"

Do not create or push a local tag first. Record the release URL and confirm the release and workflow resolve to head_sha.