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.
• Execute mac-release directly so its privileged Bash shebang ignores startup hooks; if an explicit interpreter is unavoidable, use /bin/bash -p, never plain bash mac-release.
• Keep app-specific build/package/sign behavior in repo scripts unless it is already manifest-driven.
• Never print private key material.
• Upload app/dSYM assets to a draft before publication. After a failure, preserve the release, tags, appcast commit, and local edits; inspect existing state and resume the failed step instead of deleting or retagging a possibly published release.
• Prefer MAC_RELEASE_SPARKLE_OP_REF for headless release signing when the key is in 1Password; otherwise prefer Keychain Sparkle signing. SPARKLE_PRIVATE_KEY_FILE is an explicit local 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
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release codesign-run [--with-package-secrets] -- <command> [args...]
/Users/steipete/Projects/agent-scripts/skills/release-mac-app/scripts/mac-release package-run -- <command> [args...]

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_SPARKLE_OP_REF — exact op://Vault/Item/field reference for the Sparkle EdDSA private key. The helper resolves it inside the shared op-work tmux session, writes only a mode-0600 temporary key file, validates its public key against SUPublicEDKey, and removes it on success or failure.
• MAC_RELEASE_SPARKLE_OP_ACCOUNT and MAC_RELEASE_SPARKLE_OP_USE_SERVICE_ACCOUNT override the primary 1Password account/service-account mode for the Sparkle reference. Service-account-backed refs should set service-account mode to 1.
• 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_ENV_REFS — ';'-separated NAME=op://Vault/Item/field entries resolved in the same credential pass and exported for the package command (item names may contain spaces, hence ';'). Already-exported names are preferred; refs only trigger an op read when missing. Example: NPM_TOKEN=op://Molty/npm Registry - steipete - Release Automation/registry_token.
• 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 read so the personal desktop account handles it.

1Password rules:

• Prefer already-exported env vars first; no op call if all MAC_RELEASE_OP_FIELDS are present.
• If fields are missing, read configured package and codesign items in one tmux command for the whole release.
• Provider stderr and parser exceptions are discarded; failed reads stop with fixed provider-read, JSON/schema, missing-field, or parser-failure diagnostics, without values or field labels.
• Direct env-reference handoffs use Bash %q to preserve captured values safely on Bash 3.2; command substitution still strips terminal newlines from op read output.
• Resolve MAC_RELEASE_SPARKLE_OP_REF without exposing the private key in the generated environment file or logs; only the temporary file path crosses the helper boundary.
• 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.
• Never allow a release to reach app packaging with an unprepared Developer ID keychain. No SecurityAgent password windows during release; fail the signing canary first.
• For non-app release scripts, use codesign-run instead of copying keychain setup into the repository. Supply the codesign manifest fields through .mac-release.env or explicit MAC_RELEASE_CODESIGN_* environment configuration. It loads only codesign credentials by default; pass --with-package-secrets when the wrapped release script also needs the configured package/notary fields in the same 1Password pass. It runs the bounded signing canary, scopes codesign through the managed-keychain shim, and restores/relocks before returning.
• Use package-run for notarization/package credentials when no signing operation is required. It never resolves, prepares, or unlocks the Developer ID keychain and strips signing and Sparkle authority from the child.
• Disable shell xtrace and verbose mode before loading release secrets. Arm cleanup before keychain/search-list mutations, restore the dedicated keychain's original lock policy and user search list, and relock it after packaging.

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.