Mac App Release
用於 BlackBar、RepoBar、CodexBar、Trimmy 以及類似使用 Sparkle 更新的 macOS 應用程式。
規則
- 在應用程式儲存庫中工作。
- 讀取
.mac-release.env;這是儲存庫擁有的發布清單。 - 使用此技能的
scripts/mac-release進行共享的發布/appcast/驗證工作。 - 將應用程式特定的建置/打包/簽署行為保留在儲存庫腳本中,除非它已經由清單驅動。
- 絕不列印私鑰資料。
- 優先使用 Keychain 進行 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_ZIPMAC_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(僅本機備用路徑;當檔案不存在時使用 Keychain)MAC_RELEASE_EXTRA_ASSET_PATTERNSMAC_RELEASE_EXTRA_ASSET_WAIT_SECONDSMAC_RELEASE_EXTRA_ASSET_WAIT_INTERVALMAC_RELEASE_OP_ITEM+MAC_RELEASE_OP_FIELDS用於所需的打包機密。發布輔助程式會透過一個持久的 tmux session 使用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 簽署。Keychain 必須是可替換的、專用於發布自動化、與預設 Keychain 分開、不與互動使用共用,並且只包含一個簽署私鑰。輔助程式擁有該金鑰,並可能會永久將其分割區 ACL 標準化為apple-tool:,apple:,codesign:。在預檢完成後,相同的 tmux 憑證傳遞會讀取keychain_path和keychain_password,取得每個使用者的發布鎖,透過私有的檔案描述符將密碼提供給 CLI PTY,在不隱藏現有 Keychain 的情況下前置 Keychain,驗證 Developer ID Application 的 canary,透過暫時的codesign --keychainshim 限定套件簽署範圍,然後恢復暫時狀態、重新鎖定並釋放鎖。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會覆寫 codesign 憑證項目的預設值;帳號、保管庫和服務帳號模式否則繼承主要項目的設定。將保管庫設為空且服務帳號模式設為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 指令中為整個發布讀取配置的套件和 codesign 項目。
- 僅在指定了保管庫或
MAC_RELEASE_OP_USE_SERVICE_ACCOUNT=1時使用服務帳號模式。 - 不要在新的 shell 中重試
op讀取;僅在明確的使用者指示後,從同一個 tmux session 重新執行。 - 絕不允許在 Developer ID Keychain 未準備好的情況下進行應用程式打包發布。發布期間不應出現 SecurityAgent 密碼視窗;應先讓簽署 canary 失敗。
- 對於非應用程式發布腳本,使用
codesign-run而不是將 keychain 設定複製到儲存庫中。透過.mac-release.env或明確的MAC_RELEASE_CODESIGN_*環境配置提供 codesign 清單欄位。它預設僅載入 codesign 憑證;當包裝的發布腳本在同一次 1Password 傳遞中也需要配置的套件/公證欄位時,傳遞--with-package-secrets。它會執行綁定的簽署 canary,透過受管理的 keychain shim 限定codesign範圍,並在返回前恢復/重新鎖定。 - 在載入發布機密之前停用 shell xtrace 和 verbose 模式。在 keychain/搜尋清單變更之前清理。恢復專用 keychain 的原始鎖定策略和使用者搜尋清單,並在打包後重新鎖定它。
完成
- appcast 條目包含 URL、長度、Sparkle 簽章。
- 下載的 enclosure 可通過 Sparkle 驗證。
- 解壓縮後的應用程式通過
codesign、spctl和stapler validate。 - GitHub Release 包含應用程式 zip、dSYM zip(如果已配置)以及應用程式特定的額外構件。
- 發布說明與更新日誌的章節相符。
- 在驗證發布後,在應用程式儲存庫中將更新日誌推送到下一個修補程式的
Unreleased。