Automate channel-aware Sparkle appcast generation and publishing in the release workflow

[schuyler]

Context

#129 lands the in-app Sparkle 2 migration: single feed at https://macdown.app/sparkle/macdown3000/stable/appcast.xml, pre-releases delivered as a beta channel in that one appcast (the old dual stable/testing feed scheme is retired), EdDSA signing with the public key in Info.plist (placeholder until the real key is generated).

The Nov 2025 automation plan on #129 predates the channel decision and assumed separate stable/testing appcast files routed by directory — it needs a redesign around a single channel-aware appcast before implementation.

Scope

Automate appcast generation and publishing in .github/workflows/release.yml:

1. Channel-aware generation: run Sparkle's generate_appcast with --channel beta for pre-release version tags (-beta, -alpha, -rc), no channel for stable tags; one appcast file containing both, with history preserved (download existing appcast before regenerating).
2. EdDSA signing via a SPARKLE_EDDSA_PRIVATE_KEY GitHub secret; validate secrets up front, clean up key material afterward (even on failure).
3. Publishing: upload to macdown.app hosting (mechanism TBD — SSH per the original plan, or a simpler alternative if hosting has changed), with retry + known_hosts pinning if SSH.
4. Docs: extend plans/release-process.md with the automated flow and required secrets.

Prerequisites (manual, before this can be tested)

• Real EdDSA keypair generated offline (generate_appcast --generate-keys); public key replaces the placeholder SUPublicEDKey in MacDown-Info.plist; private key stored as the GitHub secret and never committed.
• Hosting for the appcast at the SUFeedURL path (currently 503).
• Re-sign Sparkle's nested components in the release workflow (release-blocking after #129) #553 (nested Sparkle component re-signing) — releases are blocked on that regardless.

First real test should be a beta tag so failures don't affect the stable channel.

Related to #129

[schuyler]

Three corrections to the scope above, from tracing the actual publishing path.

Publishing is a commit to docs/, not SSH.

GitHub Pages serves macdown.app from this repo: source.branch = main, source.path = /docs, cname = macdown.app, legacy Jekyll build. docs/_config.yml excludes only Gemfile, Gemfile.lock, README.md, and vendor, so a static XML file with no front matter is copied through verbatim.

That makes docs/sparkle/macdown3000/stable/appcast.xml resolve to exactly the SUFeedURL the app ships with. Publishing is therefore a commit — which removes item 3's SSH mechanism, the known_hosts pinning, and the retry logic around them. .github/workflows/update-website.yml already commits into docs/ and already holds contents: write.

Generation has to run after stapling.

Scoping this into release.yml does not work. The DMG that release.yml uploads is unstapled; staple-release.yml replaces the asset afterward. The appcast records an EdDSA signature and a byte length over the file users actually download, so an appcast generated in release.yml would describe a file that no longer exists at that URL, and every update would fail verification.

update-website.yml is the right hook: it triggers on workflow_run for "Staple and Publish Release", after the final asset is in place.

Two API details.

• The generator is Pods/Sparkle/bin/generate_keys, not generate_appcast --generate-keys.
• The key reaches both sign_update and generate_appcast through --ed-key-file -, reading stdin: echo "$SECRET" | ./generate_appcast --ed-key-file - <dir>. -s <key> is marked "(DEPRECATED) … no longer supported for newly generated keys" in Sparkle 2.9.5's help for both tools, and this key is newly generated, so -s will not work at all.

Prerequisite status.

• EdDSA keypair: generated. SUPublicEDKey in MacDown/MacDown-Info.plist holds the real public key, and the private half is backed up outside the login Keychain. It still needs storing as the SPARKLE_EDDSA_PRIVATE_KEY secret before this work can be tested.
• Hosting: resolved by the docs/ path above — nothing separate to arrange.
• Re-sign Sparkle's nested components in the release workflow (release-blocking after #129) #553: addressed by Re-sign Sparkle's nested components for notarization #557.

--channel is present in generate_appcast, so channel-aware generation works as item 1 assumes.

[schuyler]

Requirements

Design decisions for this work, resolving the open items in the scope above.

Placement: two jobs at the end of staple-release.yml

Not update-website.yml. That workflow runs on ubuntu-latest, and Sparkle's
sign_update and generate_appcast are macOS Mach-O binaries that also come
from Pods/, which is gitignored — so it has neither the tools nor a runtime
for them. Putting them there costs a macos-14 runner, a pod install or a
Sparkle tarball fetch, and a re-download of the DMG.

staple-release.yml already runs on macos-14, already holds the stapled DMG
on disk, and already knows the tag. The appcast step goes after the
gh release upload --clobber that puts the stapled asset at its final URL:

• staple (macos-14, existing job) — signs the local stapled DMG and
  reads CFBundleVersion / CFBundleShortVersionString from the app inside
  it, emitting signature, length, and versions as job outputs.
• publish-appcast (ubuntu-latest, new, needs: staple) — checks out
  main, merges the item into docs/sparkle/macdown3000/stable/appcast.xml,
  commits, pushes.

The macOS job does only what requires macOS; the git work happens on main
rather than the detached tag checkout. Signatures are public, so passing them
between jobs is not a secret exposure.

Mechanism: sign_update plus a merge script, not generate_appcast

generate_appcast --download-url-prefix prepends a single prefix to every
enclosure. GitHub release URLs embed the tag
(/releases/download/v3000.1.0/MacDown-3000.1.0.dmg), so no single prefix can
produce them — its output would need post-processing regardless. It also
derives its item set from archives present in the directory, so preserving
history would mean re-downloading past DMGs on every release, and it would need
--maximum-deltas 0 since delta files have nowhere to be hosted.

Instead, sign_update produces sparkle:edSignature and length for the one
new DMG, and Tools/update_appcast.py merges a single <item> into the
existing appcast. This preserves history exactly, is idempotent by version, and
gives exact control over the enclosure URL and channel.

Channel assignment follows the existing pre-release detection: a
sparkle:channel of beta for -alpha/-beta/-rc tags, no channel element
for stable. MPMainController.m already implements
allowedChannelsForUpdater: returning {"beta"} when the pre-release
preference is set, so stable installs ignore beta items.

Both tools take the key via --ed-key-file - on stdin. -s <key> is
deprecated in Sparkle 2.9.5 and unsupported for newly generated keys.

Tests

Tools/update_appcast.py takes a DMG path and a tag, so the same script CI
calls is runnable by hand — op read "op://Personal/MacDown Sparkle EdDSA/password" | ...
— as the documented repair path when CI fails or an entry needs fixing.

A stdlib unittest suite covers: first-ever appcast creation, appending to an
existing one, idempotent re-run on an unchanged version, channel tagging,
item ordering, and malformed input. A small CI job runs it on pull requests.
No new dependencies.

Release notes

The CHANGELOG.md section for the version, embedded as CDATA in <description>.
staple-release.yml already extracts it with awk for the release notes.
Renders inline in Sparkle's dialog and needs no network at update-check time.

Retention

Every item is kept. Each is roughly a kilobyte, Sparkle selects the newest
applicable item for the allowed channels, and the history is useful to anyone
updating from an old install.

Correction to the comment above

SPARKLE_EDDSA_PRIVATE_KEY is set as a repository secret (2026-08-04T19:49:49Z,
five minutes after that comment was written). No prerequisite remains
outstanding: the keypair exists, the public half is in MacDown-Info.plist,
hosting resolves to the docs/ path, and #553 was addressed by #557.

Out of scope

CFBundleVersion is git rev-list --count HEAD, and Sparkle orders updates on
it. Under the release-branch model a beta cut from release/3000.1 can carry a
higher count than a later stable hotfix from release/3000.0, which would make
Sparkle offer the beta as the newer build. Tracked separately; it is a property
of the versioning scheme rather than of appcast plumbing.

First real exercise should be a beta tag, so a failure cannot reach the stable
channel.