release-mac-app

name	release-mac-app
description	macOS app release: Sparkle, notarization, GitHub Release, Homebrew, closeout.

Mac App Release

Use for BlackBar, RepoBar, CodexBar, Trimmy, and similar Sparkle-updated macOS apps.

Rules

• Work from the app repo.
• Read .mac-release.env; it is the repo-owned release manifest.
• Use scripts/mac-release from this skill for shared release/appcast/verify work.
• Keep app-specific build/package/sign behavior in repo scripts unless it is already manifest-driven.
• Never print private key material.
• Prefer Keychain Sparkle signing. SPARKLE_PRIVATE_KEY_FILE is an explicit override only.

Commands

/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release status
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release notes [version] [output.md]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release changelog-html <version> [CHANGELOG.md]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release make-appcast <zip> [feed-url]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release verify-appcast [version]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release check-assets [tag]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release release

Manifest

Each repo owns .mac-release.env. It must contain no secrets.

Required:

• MAC_RELEASE_APP_NAME
• MAC_RELEASE_REPO
• MAC_RELEASE_BUNDLE_ID
• MAC_RELEASE_VERSION_FILE
• MAC_RELEASE_APPCAST
• MAC_RELEASE_FEED_URL
• MAC_RELEASE_DOWNLOAD_URL_PREFIX
• MAC_RELEASE_APP_ZIP
• either MAC_RELEASE_INFO_PLIST or MAC_RELEASE_SUPUBLIC_ED_KEY
• MAC_RELEASE_PACKAGE_CMD

Common optional:

• MAC_RELEASE_PRECHECK
• MAC_RELEASE_SOURCE_FILES (space-separated app helper files to source before expanding artifact names)
• MAC_RELEASE_DSYM_ZIP
• MAC_RELEASE_REQUIRE_DSYM=0 for app-only releases
• MAC_RELEASE_ARTIFACT_PREFIX
• MAC_RELEASE_TAG_SIGNED
• MAC_RELEASE_TAG_FORCE
• MAC_RELEASE_RELEASE_BRANCH
• MAC_RELEASE_SPARKLE_ACCOUNT
• MAC_RELEASE_SPARKLE_CHANNEL
• MAC_RELEASE_GENERATE_APPCAST_ARGS
• MAC_RELEASE_RUN_SPARKLE_UPDATE_TEST
• MAC_RELEASE_SIGNING_KEY_FILE (local fallback path only; Keychain is used when the file is absent)
• MAC_RELEASE_EXTRA_ASSET_PATTERNS
• MAC_RELEASE_EXTRA_ASSET_WAIT_SECONDS
• MAC_RELEASE_EXTRA_ASSET_WAIT_INTERVAL
• MAC_RELEASE_OP_ITEM + MAC_RELEASE_OP_FIELDS for required packaging secrets. The release helper reads the known item once via op inside one persistent tmux session, then exports the requested fields for the package command.
• MAC_RELEASE_OP_ACCOUNT defaults to my.1password.com; MAC_RELEASE_OP_VAULT, MAC_RELEASE_OP_TMUX_SESSION, MAC_RELEASE_OP_WAIT_SECONDS are optional. Without a vault, service-account token env is unset for that single op read so the personal desktop account handles it.
• MAC_RELEASE_RUN_LOGIN_SHELL=1 opts command hooks back into bash -lc; default hooks use env -u BASH_ENV bash -c so shell startup files cannot override exported release secrets.

1Password rules:

• Prefer already-exported env vars first; no op call if all MAC_RELEASE_OP_FIELDS are present.
• If fields are missing, use exactly one op item get inside tmux for the whole release.
• Use service-account mode only with an explicit vault or MAC_RELEASE_OP_USE_SERVICE_ACCOUNT=1.
• Do not retry op reads in a fresh shell; rerun only from the same tmux session after explicit user direction.

Done

• appcast entry has URL, length, Sparkle signature.
• downloaded enclosure verifies with Sparkle.
• extracted app passes codesign, spctl, and stapler validate.
• GitHub release has app zip, dSYM zip when configured, plus app-specific extra assets.
• release notes match the changelog section.
• after verified release, bump changelog to next patch Unreleased in the app repo.