Release process (CodexBar)

SwiftPM-only; package/sign/notarize manually (no Xcode project). Sparkle feed is served from GitHub Releases. Checklist below merges Trimmy’s release flow with CodexBar specifics.

Must read first: open the master macOS release guide at ~/Projects/agent-scripts/docs/RELEASING-MAC.md alongside this file and reconcile any differences in favor of CodexBar specifics before starting a release.

Expectations

When someone says “release CodexBar”, do the entire end-to-end flow: bump versions/CHANGELOG, build, sign and notarize, upload the zip to the GitHub release, generate/update the appcast with the new signature, publish the tag/release, and verify the enclosure URL responds with 200/OK and installs via Sparkle (no 404s or stale feeds).

Release automation notes (Scripts/release.sh)

Always forces a fresh build/notarization (no cached artifacts) before publishing.
Fails fast if: git tree is dirty, the top changelog section is still “Unreleased” or mismatched, the target version already exists in the appcast, or the build number is not greater than the latest appcast entry.
Sparkle key probe runs up front; appcast entry + signature verified automatically after generation.
Release notes are extracted directly from the current changelog section and passed to the GitHub release (no manual notes flag needed).
Sparkle appcast notes are generated as HTML from the same changelog section and embedded into the appcast entry.
Requires tools/env on PATH: swiftformat, swiftlint, swift, sign_update, generate_keys, generate_appcast, gh, python3, zip, curl, plus APP_STORE_CONNECT_*. SPARKLE_PRIVATE_KEY_FILE is only needed when overriding the default Keychain Sparkle key.

Prereqs

Xcode 26+ installed at /Applications/Xcode.app (for ictool/iconutil and SDKs).
Developer ID Application cert installed: Developer ID Application: Peter Steinberger (Y5PE65HELJ).
ASC API creds in env: APP_STORE_CONNECT_API_KEY_P8, APP_STORE_CONNECT_KEY_ID, APP_STORE_CONNECT_ISSUER_ID.
Sparkle keys: public key expectation is in .mac-release.env; CodexBar still uses the older shared AGCY key, so the manifest includes the local Dropbox fallback path. SPARKLE_PRIVATE_KEY_FILE overrides it.
Ensure shell has release env vars loaded (usually source ~/.profile) before running Scripts/release.sh.
Shared release helper: Scripts/mac-release resolves MAC_RELEASE_TOOL, sibling ../agent-scripts, or ~/Projects/agent-scripts.

Icon (glass .icon → .icns)

./Scripts/build_icon.sh Icon.icon CodexBar

Uses Xcode’s ictool + transparent padding + iconset → Icon.icns.

Build, sign, notarize (universal: arm64 + x86_64)

./Scripts/sign-and-notarize.sh

What it does:

swift build -c release --arch arm64 and swift build -c release --arch x86_64
Packages CodexBar.app with Info.plist and Icon.icns
Embeds Sparkle.framework, Updater, Autoupdate, XPCs
Codesigns everything with runtime + timestamp (deep) and adds rpath
Zips to CodexBar-macos-universal-<version>.zip
Submits to notarytool, waits, staples, validates

Gotchas fixed:

Sparkle needs signing for framework, Autoupdate, Updater, XPCs (Downloader/Installer) or notarization fails.
Use --timestamp and --deep when signing the app to avoid invalid signature errors.
Avoid unzip — it can add AppleDouble ._* files that break the sealed signature and trigger “app is damaged”. Use Finder or ditto -x -k CodexBar-<ver>.zip /Applications. If Gatekeeper complains, delete the app bundle, re-extract with ditto, then spctl -a -t exec to verify.
Manual sanity check before uploading: find CodexBar.app -name '._*' should return nothing; then spctl --assess --type execute --verbose CodexBar.app and codesign --verify --deep --strict --verbose CodexBar.app should both pass on the packaged bundle.

Appcast (Sparkle)

After notarization, or let Scripts/release.sh do this:

./Scripts/make_appcast.sh CodexBar-macos-universal-0.1.0.zip \
  https://raw.githubusercontent.com/steipete/CodexBar/main/appcast.xml

Generates HTML release notes from CHANGELOG.md (via Scripts/changelog-to-html.sh) and embeds them into the appcast entry. Uploads not handled automatically—commit/publish appcast + zip to the feed location (GitHub Releases/raw URL).

Tag & release

./Scripts/release.sh

Homebrew (Cask)

CodexBar ships a Homebrew Cask in ../homebrew-tap. When installed via Homebrew, CodexBar disables Sparkle and the app must be updated via brew.

After publishing the GitHub release, .github/workflows/release-cli.yml builds the macOS, glibc Linux, and static musl Linux CLI tarballs for arm64 and x86_64, uploads them plus checksums, then dispatches the Homebrew tap update for both the CLI formula and app cask. Homebrew continues to use the glibc Linux assets. If the final dispatch is rate-limited, the tarballs and app zip may still be present; rerun or manually update the tap formula/cask from the published assets.

Checklist (quick)

Troubleshooting

White plate icon: regenerate icns via build_icon.sh (ictool) to ensure transparent padding.
Notarization invalid: verify deep+timestamp signing, especially Sparkle’s Autoupdate/Updater and XPCs; rerun package + sign-and-notarize.
App won’t launch: ensure Sparkle.framework is embedded under Contents/Frameworks and rpath added; codesign deep.
App “damaged” dialog after unzip: re-extract with ditto -x -k, removing any ._* files, then re-verify with spctl.
Update download fails (404): ensure the release asset referenced in appcast exists and is published in the corresponding GitHub release; verify with curl -I <enclosure-url>.