Mac 应用发布
用于 BlackBar、RepoBar、CodexBar、Trimmy 以及类似的 Sparkle 更新型 macOS 应用。
规则
- 在应用仓库中执行操作。
- 读取
.mac-release.env;它是仓库拥有的发布清单文件。 - 使用本技能的
scripts/mac-release进行共享的发布/应用更新/验证工作。 - 对于构建/打包/签名等应用特有行为,除非已由清单驱动,否则保留在仓库脚本中。
- 绝不打印私钥材料。
- 优先使用钥匙串进行 Sparkle 签名。仅在显式覆盖时使用
SPARKLE_PRIVATE_KEY_FILE。
命令
/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...]
清单
每个仓库拥有自己的 .mac-release.env。它不得包含任何机密信息。
必需项:
MAC_RELEASE_APP_NAMEMAC_RELEASE_REPOMAC_RELEASE_BUNDLE_IDMAC_RELEASE_VERSION_FILEMAC_RELEASE_APPCASTMAC_RELEASE_FEED_URLMAC_RELEASE_DOWNLOAD_URL_PREFIXMAC_RELEASE_APP_ZIP- 要么
MAC_RELEASE_INFO_PLIST,要么MAC_RELEASE_SUPUBLIC_ED_KEY MAC_RELEASE_PACKAGE_CMD
常用可选:
MAC_RELEASE_PRECHECKMAC_RELEASE_SOURCE_FILES(以空格分隔的应用辅助文件,在展开构件名称前引入)MAC_RELEASE_DSYM_ZIPMAC_RELEASE_REQUIRE_DSYM=0用于仅应用发布MAC_RELEASE_ARTIFACT_PREFIXMAC_RELEASE_TAG_SIGNEDMAC_RELEASE_TAG_FORCEMAC_RELEASE_RELEASE_BRANCHMAC_RELEASE_SPARKLE_ACCOUNTMAC_RELEASE_SPARKLE_CHANNELMAC_RELEASE_GENERATE_APPCAST_ARGSMAC_RELEASE_RUN_SPARKLE_UPDATE_TESTMAC_RELEASE_SIGNING_KEY_FILE(仅本地回退路径;当文件不存在时使用钥匙串)MAC_RELEASE_EXTRA_ASSET_PATTERNSMAC_RELEASE_EXTRA_ASSET_WAIT_SECONDSMAC_RELEASE_EXTRA_ASSET_WAIT_INTERVALMAC_RELEASE_OP_ITEM+MAC_RELEASE_OP_FIELDS用于所需的打包机密。发布辅助脚本通过一个持久的 tmux 会话中的一次op读取已知条目,然后为打包命令导出请求的字段。MAC_RELEASE_OP_ACCOUNT默认为my.1password.com;MAC_RELEASE_OP_VAULT、MAC_RELEASE_OP_TMUX_SESSION、MAC_RELEASE_OP_WAIT_SECONDS为可选项。如果没有保险库,则取消设置该单次op读取的服务账户令牌环境变量,以便个人桌面账户进行处理。MAC_RELEASE_CODESIGN_IDENTITY+MAC_RELEASE_CODESIGN_OP_ITEM+MAC_RELEASE_CODESIGN_KEYCHAIN_MANAGED=1启用非交互式 Developer ID 签名。钥匙串必须是可替换的、专用于发布自动化、与默认钥匙串分离、不与交互式使用共享,并且仅包含一个签名私钥。辅助脚本会拥有该钥匙串的权限,并可能永久规范化该钥匙的分区 ACL 为apple-tool:,apple:,codesign:。预检查后,同一个 tmux 凭据传递会读取keychain_path和keychain_password,获取每个用户的发布锁,通过私有文件描述符将密码提供给 CLI PTY,在不隐藏现有钥匙串的情况下预置该钥匙串,验证一个 Developer ID Application 金丝雀,通过临时codesign --keychain垫片限定包签名,然后恢复临时状态、重新上锁并释放锁。MAC_RELEASE_CODESIGN_OP_ACCOUNT、MAC_RELEASE_CODESIGN_OP_VAULT、MAC_RELEASE_CODESIGN_OP_USE_SERVICE_ACCOUNT、MAC_RELEASE_CODESIGN_OP_PATH_FIELD和MAC_RELEASE_CODESIGN_OP_PASSWORD_FIELD覆盖代码签名凭据条目的默认值;账户、保险库和服务账户模式否则继承主条目设置。将保险库设置为空且服务账户模式为0以用于个人桌面账户条目。也可以直接提供MAC_RELEASE_CODESIGN_KEYCHAIN+MAC_RELEASE_CODESIGN_KEYCHAIN_PASSWORD。MAC_RELEASE_RUN_LOGIN_SHELL=1将命令钩子切换回bash -lc;默认钩子使用env -u BASH_ENV bash -c,因此 shell 启动文件无法覆盖导出的发布机密。
1Password 规则:
- 优先使用已导出的环境变量;如果所有
MAC_RELEASE_OP_FIELDS都存在,则不调用op。 - 如果字段缺失,则在一个 tmux 命令中为整个发布读取配置好的打包和代码签名条目。
- 仅在有显式保险库或
MAC_RELEASE_OP_USE_SERVICE_ACCOUNT=1时使用服务账户模式。 - 不要在新 shell 中重试
op读取;仅在得到用户明确指示后从同一个 tmux 会话重新运行。 - 决不允许发布在 Developer ID 钥匙串未准备好的情况下进入应用打包阶段。发布期间不得出现 SecurityAgent 密码窗口;首先使签名金丝雀失败。
- 对于非应用发布脚本,请使用
codesign-run,而不是将钥匙串设置复制到仓库中。通过.mac-release.env或显式的MAC_RELEASE_CODESIGN_*环境配置提供代码签名清单字段。默认仅加载代码签名凭据;当被封装的发布脚本在同一 1Password 传递中也需要配置的打包/公证字段时,传递--with-package-secrets。它会运行绑定的签名金丝雀,通过托管钥匙串垫片限定codesign,并在返回前恢复/重新上锁。 - 在加载发布机密之前禁用 shell xtrace 和 verbose 模式。在钥匙串/搜索列表变更之前启用清理机制,恢复专用钥匙串的原始锁定策略和用户搜索列表,并在打包后重新锁定。
完成
- appcast 条目包含 URL、长度、Sparkle 签名。
- 下载的 enclosure 可以通过 Sparkle 验证。
- 提取的应用通过
codesign、spctl和stapler validate。 - GitHub Release 包含应用 zip、配置时的 dSYM zip,以及应用特定的额外资源。
- 发布说明与变更日志章节匹配。
- 在验证发布后,将应用仓库中的变更日志更新为下一个补丁版本的
Unreleased。